居民健康卡应用接口技术规范教材

居民健康卡应用接口技术规范北京冠新医卫软件科技有限公司2015年12月目录目录2前言41适用范围52规范性引用文件53术语和定义53.1居民健康卡 Residents Health Card53.2CPU卡53.3卡片操作系统（COS） Card Operating System53.4加密算法 Cryptographic Algorithm53.5对称加密算法 Symmetric Cryptographic Algorithm63.6非对称加密算法 Asymmetric Cryptographic Algorithm63.7密钥 Key63.8对称密钥 Symmetric Key63.9非对称密钥 Asymmetric Key63.10公钥 Public Key63.11私钥 Private Key63.12数字签名 Digital Signature63.13SM2算法73.14SM3算法74缩略语85应用模型96接口函数106.1设备管理126.2用户卡读写136.3卡算法服务276.4错误码定义29附录A VC程序用例301设备管理312用户卡读写323卡算法服务53附录B55前言本规范涉及的数据项定义、命令数据符合卫生部定义的居民健康卡系列规范。本规范涉及的密码算法按照国家密码管理部门的要求使用。本规范依据居民健康卡技术规范，居民健康卡应用规范，居民健康卡安全存取模块(SAM)卡规范，居民健康卡安全存取模块(SAM)卡命令集，居民健康卡用户卡命令集，结合医疗服务和用户管理业务流程，描述定义居民健康卡中数据存取访问接口。1 适用范围本文确定居民健康卡中数据存取的应用编程接口。基于符合规范的设备如（读写机具、SAM卡、用户卡）以及居民健康卡应用规范的用户卡中的定义的特定数据项，依据居民健康卡在医疗业务，用户管理等流程中的应用，描述定义所需接口函数、参数数据类型、以及接口的调用方式。2 规范性引用文件下列文件中的条款通过本规范的引用而成为本规范的条款居民健康卡技术规范居民健康卡应用规范居民健康卡安全存取模块(SAM)卡规范居民健康卡安全存取模块(SAM)卡命令集居民健康卡用户卡命令集以下术语和定义适用于本规范。3 术语和定义3.1 居民健康卡 Residents Health Card居民健康卡是中华人民共和国居民拥有的，在医疗卫生服务活动中用于身份识别，满足健康信息存储，实现跨地区和跨机构就医、数据交换和费用结算的基础载体，是计算机可识别的CPU卡。3.2 CPU卡 带有中央处理器（CPU）、存储单元以及卡片操作系统的集成电路卡。3.3 卡片操作系统（COS） Card Operating SystemCPU卡芯片中存储和运行的，以保护应用数据和程序的机密性和完整性，控制CPU卡芯片与外界信息交换为目的的嵌入式软件。3.4 加密算法 Cryptographic Algorithm为了隐藏或显现数据信息内容的变换算法。3.5 对称加密算法 Symmetric Cryptographic Algorithm加密密钥可以从解密密钥中推算出来，反过来也成立，在大多数算法中加/解密密钥是相同的。3.6 非对称加密算法 Asymmetric Cryptographic Algorithm加密算法的加密密钥和解密密钥是不一样的，不能由一个密钥推导出另一个密钥。3.7 密钥 Key加密转换中控制操作的符号序列。3.8 对称密钥 Symmetric Key在对称加密算法中使用的密钥。3.9 非对称密钥 Asymmetric Key在非对称加密算法中使用的密钥，包括公钥和私钥。3.10 公钥 Public Key在一个实体使用的非对称密钥对中可以被公众使用的密钥。在数字签名方案中，公钥用于验证。3.11 私钥 Private Key在一个实体使用的非对称密钥对中仅被该实体使用的密钥。在数字签名方案中，私钥用于签名。3.12 数字签名 Digital Signature 对数据的一种非对称加密变换。该变换可以使数据接收方确认数据的来源和完整性，保护数据发送方发出和接收方收到的数据不被第三方篡改，也保护数据发送方发出的数据不被接收方篡改。3.13 SM2算法SM2 algorithm ，一种国家商用密码非对称密码算法，密钥长度为256比特。3.14 SM3算法SM3 algorithm ，一种国家商用密码密码杂凑算法，输出长度为256比特。4 缩略语下列缩略语适用于本规范： 缩略语中文名英文名0-9 A-F十六进制数字API应用编程接口Application Programming InterfaceAPDU应用协议数据单元Application Protocol Data UnitPKI公钥基础设施Public Key InfrastructurePIN个人身份识别码Personal Identification Numberan字母数字型Alphanumericans特殊字母数字型Alphanumeric Specialb二进制BinaryBER基本编码规则Basic Encoding Rulescn压缩数字Compressed NumericDDF目录定义文件Directory Definition FileDF专用文件Dedicated FileEF基本文件Elementary FileFCI文件控制信息File Control InformationFID文件标识符File IdentifierIC集成电路Integrated CircuitISO 国际标准化组织International Organization for StandardizationMAC报文鉴别代码Message Authentication CodeMF 主控文件Master FileSAM安全存取模块Secure Access ModuleTLV标签、长度、值Tag Length Value5 应用模型根据居民健康卡应用规范，卡中存放了卡片基本信息，用户个人基本信息，联系人信息、医学警示生物标识信息，住院信息、门诊记录信息以及相应的证书签名信息。总共记录的数据项有380多个类别，这些数据项分布在卡中不同目录下不同的文件中。卡中不同的数据文件，根据其存放数据的不同，具有不同的读写权限。具体请参见居民健康卡安全存取模块（SAM）卡技术规范附录表A4 密钥配置表。要读写居民健康卡，需要使用符合卫生部颁布的相关规范的读写机具和SAM卡，完成读写数据所需要的权限控制，在读取特定数据前，需要根据其所在文件不同，依据密钥配置表去获取外部认证所需要的密钥标识用途，密钥版本等信息。然后通过发送指令到SAM卡进行密钥分散，使用SM1算法加密数据取得SAM卡计算外部认证需要的认证数据，再发送给用户卡完成外部认证以取得相应的权限，此后再根据所读取的字段所在文件、记录号等信息进行数据读写。为了简化上层应用的开发，读写接口将这一过程进行了封装，应用开发者只需要通过接口规范提供的读写函数，设置所需读写居民健康卡中的单个或多个数据项，就可以完成数据的读写操作。这样应用层就可以不需要关心读写机具、用户卡、SAM卡之间的交互，只需要针对所需要数据完成业务流程的设计开发。6 接口函数接口函数列表如下：函数名功能备注iDOpenPort打开设备返回设备操作句柄iDClosePort关闭设备PowerOn设备复位返回复位信息SendAPDU发送指令iVerifyPIN验证PIN校验SAM卡PINiChange_Pin修改PIN修改SAM卡PINiReader_SAM_Public读取SAM卡公共信息该函数取得SAM卡片公共信息文件iReader_SAM_Terminal读取SAM卡片终端信息该函数取得SAM卡片的终端信息文件iReader_SAM_PublicApp读取SAM公共应用信息该函数取得SAM卡片的居民健康卡应用的公共信息文件iReader_SAM_OrgCertificate读取SAM卡上的健康卡发卡机构证书该函数取得SAM卡片的居民健康卡发卡机构证书文件iReader_SAM_Certificate读取SAM卡的机构证书该函数取得SAM卡片的SAM卡机构证书iR_DDF1EF05Info读取卡中DDF1EF05中的数据根据函数各参数读取卡中数据(发卡机构基本数据文件)iR_DDF1EF06Info读取卡中DDF1EF06中的数据根据函数各参数读取卡中数据(持卡人基本信息数据文件)iR_DDF1EF07Info读取卡中DDF1EF07中的数据根据函数各参数读取卡中数据(照片)iR_DDF1EF08Info读取卡中DDF1EF08中的数据根据函数各参数读取卡中数据(有效期等)iW_DDF1EF08Info写入卡中DDF1EF08中的数据根据函数各参数写入卡中数据(有效期等)iR_DF01EF05Info读取卡中DF01EF05中的数据根据函数各参数读取卡中数据(地址信息文件)iW_DF01EF05Info写入卡中DDF1EF05中的数据根据函数各参数写入卡中数据(地址信息文件)iR_DF01EF06Info读取卡中DF01EF06中的数据根据函数各参数读取卡中数据(联系人信息文件)iW_DF01EF06Info写入卡中DF01EF06中的数据根据函数各参数写入卡中数据(联系人信息文件)iR_DF01EF07Info读取卡中DF01EF07中的数据根据函数各参数读取卡中数据(职业婚姻信息文件)iW_DF01EF07Info写入卡中DF01EF07中的数据根据函数各参数写入卡中数据(职业婚姻信息文件)iR_DF01EF08Info读取卡中DF01EF08中的数据根据函数各参数读取卡中数据(证件记录信息文件)iW_DF01EF08Info写入卡中DF01EF08中的数据根据函数各参数写入卡中数据(证件记录信息文件)iR_DF02EF05Info读取卡中DF02EF05中的数据根据函数各参数读取卡中数据(临床基本数据文件)iW_DF02EF05Info写入卡中DF02EF05中的数据根据函数各参数写入卡中数据(临床基本数据文件)iR_DF02EF06Info读取卡中DF02EF06中的数据根据函数各参数读取卡中数据(特殊信息数据文件)iW_DF02EF06Info写入卡中DF02EF06中的数据根据函数各参数写入卡中数据(特殊信息数据文件)iR_DF02EF07Info读取卡中DF02EF07中