密码卡调试查错指南
介绍派科信安PCIE密码卡调试时密码卡常见错误返回及解决办法。
适用范围
此手册适用于派科信安的如下PCIE密码卡：
- A系列：A11、A12
- C系列：C1
适用于派科信安的如下Mini PCIE密码卡：
- M10、M10U
- M11、M11U
适用于派科信安的如下USB密码卡：
- U11
调试第一关：设备安装与驱动加载
相关错误返回码：
| 错误定义 | 值 |
|---|---|
| SR_CANNOT_OPEN_DEVICE | 0x80000001 |
| SDR_OPENDEVICE | 0x01000005 |
错误原因：
密码卡设备文件在当前用户下没找到。
错误排查顺序：
Step1：用lspci命令（命令安装包名pciutils）或lsusb命令（命令安装包名usbutils）检查设备是否被主机识别
A11/A12密码卡：使用lspci命令，检查是否可以看到Encryption controller: Device 9118:2104 (rev 01)。
C系列密码卡：使用lsusb命令，检查是否可以看到厂商ID为9118设备ID为2104或2208的USB设备。
M系列密码卡：使用lsusb命令，检查是否可以看到厂商ID为9118设备ID为2104或2208的USB设备。
U系列密码卡：使用lsusb命令，检查是否可以看到厂商ID为9118设备ID为2208的USB设备。
如果主机识别到对应的密码卡进行到Step2。
如果主机识别不到对应的密码卡
Action1：请重新插拔试下。若主机还是识别不到，可用橡皮清洁下密码卡金手指再试下。
Action2：检查主机插槽，可能是插槽的问题！对于PCIE插槽可更换插槽再试，比如双路服务器只用1个CPU的时候有些PCIE插槽对于的CPU不存在时是没用的；有些插槽是给网卡定制的也不能用。对于MINIPCIE插槽问题可能更复杂，MINIPCIE规范里插槽上配有PCIE总线接口和USB总线接口，但实际主板可能PCIE总线接口和USB总线接口二者选一，有正好与M系列卡的总线接口需求不匹配的情况。更有定制的MINIPCIE插槽，还有与MINIPCIE插槽一模一样的MSATA接口，所以使用MINIPCIE插槽时出现主机识别不到密码卡时，先通过主板手册检查下MINIPCIE插槽是否与M系列卡匹配。
Action3：若识别问题还是没法解决，请联系我方技术支持。
Step2：检查驱动是否安装
A11/A12密码卡执行命令：
lsmod | grep PIICOCard
CMU系列密码卡执行命令：
lsmod | grep piico_ccmu
如果执行命令能找到模块进行到Step3。
如果执行命令找不到模块——驱动本身不会自动加载，这个问题比较常见
Action1：在SDK主目录下root权限执行make driver_install, 可加载驱动。
Action2：如果系统没有make命令，请用root权限insmod命令加载，建议将命令添入启动脚本。
A11/A12密码卡执行命令：
insmod <驱动目录路径>/PIICOCard.ko
CMU系列密码卡执行命令：
insmod <驱动目录路径>/piico_ccmu.ko
Action3：若insmod命令没有执行成功，请联系我方技术支持。
Step3：检查系统用户权限
驱动产生的设备文件默认只能root权限访问，普通用户无密码卡设备文件的读写权限。
Action1：加sudo命令执行用户程序。
Action2：若需要普通用户访问权限，需root权限下chmod命令修改设备文件权限。
A11/A12密码卡执行命令：
chmod go+x /dev/piico50
CMU系列密码卡执行命令：
chmod go+x /dev/PiicoMiNi0
注意：某些系统下密码卡设备文件会识别为/dev/PiicoMiNi1而非/dev/PiicoMiNi0。
调试第二关：会话密钥使用
相关错误返回码：
| 错误定义 | 值 |
|---|---|
| CCR_SESSION_KEY_EMPTY | 0x00001004 |
错误原因：
会话密钥资源在密码卡内是有限的，会话密钥分配完后无法获取。
错误排查顺序：
Step1：排查代码在获取会话密钥句柄并且会话密钥使用后是否及时调用SDF_DestroyKey接口释放该会话密钥资源。
Step2：若非代码原因，而是调试时异常退出，占用的会话密钥资源无法释放时，可使用SPII_ResetModule接口或直接重启机器来复位固定在机器上的密码卡。
调试第三关：密码卡用户登录
相关错误返回码：
| 错误定义 | 值 |
|---|---|
| CCR_PIN_CHECK_ERR | 0x00001002 |
| CCR_UKEY_CHECK_ERR | 0x000020A1 |
错误原因：
密码卡PIN口令错误和管理UKey的PIN口令错误。
错误排查顺序：
Step1：重新输入PIN测试。
Step2：若忘记管理员或操作员密码。
Action1：使用piicoToolWP工具(PIN码管理)或piicoTool工具(Ukey管理)登录超级管理员。
Action2：使用piicoToolWP工具(PIN码管理)或piicoTool工具(Ukey管理)重新注册管理员或操作员并登录。
Step3：若忘记超级管理员密码则无法恢复，必要时物理重置密码卡，整卡重新初始化。
调试第四关：密码卡卡内密钥使用
相关错误返回码：
| 错误定义 | 值 |
|---|---|
| CCR_PRIVATE_KEY_ACCESSRIGHT_VERIFY_ERR | 0x00001010 |
错误原因：
密码卡私钥权限口令码错误。
错误排查顺序：
Step1：重新输入私钥权限口令码测试。
Step2：若忘记私钥权限口令码，必要时重置密码卡，整卡重新初始化，参见《密码卡使用手册》相关章节。
相关错误返回码：
| 错误定义 | 值 |
|---|---|
| CCR_AUTHORITY_ERR | 0x00001013 |
错误原因：
密码卡卡内私钥使用前未获取私钥使用权限。
错误排查顺序：
Step1：确认代码中SDF_GetPrivateKeyAccessRight接口是否调用。
Step2：确认为用到的所有私钥索引值单独进行SDF_GetPrivateKeyAccessRight接口调用。
相关错误返回码：
| 错误定义 | 值 |
|---|---|
| CCR_KEY_PAIRE_EMPTY | 0x00002050 |
错误原因：
密码卡用户未登录或密钥不存在
错误排查顺序：
Step1：确认密码卡管理员或操作员用户已登录才可使用卡内密钥（包括公钥）。
Step2：若确实密钥不存在，可用piicoToolWP或piicoTool工具整体生成或用PiiCardManager工具单个生成。