stagex/pcsc-lite

智能卡访问中间件（SCard API/PC/SC）

镜像概述

本Docker镜像提供一个基于PC/SC标准和SCard API的中间件，用于实现应用程序与智能卡硬件的通信。作为连接上层应用与智能卡读卡器的桥梁，该镜像简化了智能卡访问流程，提供标准化接口，使开发人员无需关注底层硬件细节即可实现智能卡交互功能。

核心功能与特性

• 遵循PC/SC标准：完全兼容PC/SC（Personal Computer/Smart Card）行业规范，支持符合ISO 7816标准的智能卡
• SCard API兼容：实现完整的SCard系列API（如SCardConnect、SCardTransmit、SCardDisconnect等核心函数），确保与现有基于SCard API开发的应用程序无缝集成
• 硬件抽象：屏蔽不同品牌、型号读卡器的硬件差异，提供统一访问接口
• 多卡支持：支持同时访问多个智能卡读卡器及多张智能卡（取决于硬件配置）
• 轻量级设计：基于精简基础镜像构建，最小化资源占用，适合嵌入式环境和容器化部署
• 日志与调试：内置完善的日志系统，支持多级别日志输出，便于问题诊断和开发调试

使用场景与适用范围

• 企业身份认证：用于基于智能卡的员工身份验证、单点登录（SSO）系统
• 领域：支持银行卡、U盾等智能卡的交易验证与数据交互
• 健康：访问患者IC卡、电子健康档案（EHR）智能卡
• ***与公共服务：读取身份证、社保卡、居住证等政务智能卡
• 应用开发测试：为智能卡应用开发提供标准化测试环境，降低硬件依赖
• 物联网设备：在嵌入式物联网设备中实现智能卡身份识别与数据加密

使用方法与配置说明

前提条件

• 主机已连接智能卡读卡器并安装必要的驱动程序
• Docker引擎版本≥1.13（支持--device参数和多阶段构建镜像）
• 主机系统需支持PC/SC通信（Linux系统建议安装pcscd服务）

基本部署命令

bash
docker run -d \
  --name scard-middleware \
  --device=/dev/bus/usb:/dev/bus/usb \  # 挂载USB读卡器设备（根据实际接口调整）
  -e LOG_LEVEL=INFO \                   # 设置日志级别
  -e READER_POLL_INTERVAL=2000 \        # 读卡器轮询间隔（毫秒）
  -p 3000:3000 \                        # 暴露API端口（如提供REST/gRPC接口）
  --restart unless-stopped \
  your-registry/smartcard-middleware:latest

Docker Compose配置示例

yaml
version: '3.8'
services:
  scard-middleware:
    image: docker.xuanyuan.run/your-registry/smartcard-middleware:latest
    container_name: scard-middleware
    devices:
      - /dev/bus/usb:/dev/bus/usb  # USB读卡器设备挂载
      # 如需PCI接口读卡器，添加对应设备路径，如：/dev/pcsc:/dev/pcsc
    environment:
      - LOG_LEVEL=DEBUG                  # 调试模式日志级别
      - READER_NAME_FILTER="ACS"         # 读卡器名称过滤（支持通配符）
      - PCSCD_AUTOSTART=true             # 自动启动PC/SC守护进程
      - MAX_CONCURRENT_SESSIONS=10       # 最大并发会话数
    ports:
      - "3000:3000"                      # API访问端口
      - "2222:22"                        # 可选：SSH调试端口
    volumes:
      - ./logs:/var/log/scard-middleware  # 日志持久化
      - ./config:/etc/scard               # 配置文件挂载
    restart: unless-stopped

环境变量配置

设备挂载说明

根据读卡器接口类型，需正确挂载对应设备：

• USB接口读卡器：挂载/dev/bus/usb总线
• PCI/PCIe接口读卡器：挂载对应PCI设备（如/dev/pcsc0）
• 串口读卡器：挂载串口设备（如/dev/ttyUSB0）

验证部署

部署完成后，可通过以下命令检查服务状态：

bash
# 查看容器运行状态
docker ps | grep scard-middleware

# 查看日志输出
docker logs -f scard-middleware

# 测试读卡器检测
docker exec -it scard-middleware scard-tool --list-readers

应用集成示例

应用程序可通过以下方式与中间件交互：

1. 直接API调用：通过中间件暴露的TCP端口（默认3000）使用SCard API
2. 本地Socket：容器内应用可通过/var/run/pcscd/pcscd.comm与PC/SC守护进程通信
3. 卷挂载共享：通过共享内存或UNIX域套接字实现容器间通信

示例代码片段（Python）：

python
import PyKCS11

# 连接到中间件提供的PC/SC服务
pkcs11 = PyKCS11.PyKCS11Lib()
pkcs11.load('/usr/local/lib/libscard-middleware.so')  # 中间件库路径

# 获取读卡器列表
readers = pkcs11.getSlotList(tokenPresent=True)
if not readers:
    raise Exception("未检测到智能卡读卡器")

# 连接智能卡
session = pkcs11.openSession(readers[0])
session.login("123456")  # 智能卡PIN码

# 执行命令（示例：读取卡片ATR）
atr = session.getATR()
print(f"智能卡ATR: {ATR(atr).toString()}")

session.logout()
session.closeSession()

注意事项

1. 设备权限：确保容器对挂载的设备具有读写权限，必要时可使用--privileged参数（仅测试环境使用）
2. 读卡器兼容性：建议使用通过PC/SC认证的读卡器以确保最佳兼容性
3. 安全考虑：生产环境中应启用SSL加密并限制API访问权限，避免未授权访问
4. 性能调优：高并发场景下可适当增加MAX_CONCURRENT_SESSIONS值并调整系统资源限制
5. 日志管理：建议配置日志轮转策略，避免日志文件过大占用磁盘空间