信息安全技术智能密码钥匙应用接口规范

信息安全技术智能密码钥匙应用接口规范

国家标准 GB/T35291一2017 信息安全技术 智能密码钥匙应用接口规范 Informationsecuritytechnology一 Cryptographytokenapplieationinterfaeespeeifieationm 2017-12-29发布 2018-07-01实施 国家质量监督检验检疫总局 发布 国家标准化管理委员会国家标准
GB/35291一2017 目 次 前言 引言 范围 2 规范性引用文件 术语和定义 缩略语 结构模型 5.1层次关系 5.2设备的应用结构 数据类型定义 6.1算法标识 6.2基本数据类型 6.3常量定义 6.4复合数据类型 12 接口函数 7.1设备管理 12 7.3 访问控制 15 7. 应用管理 17 文件管理 19 7." 7.5 容器管理 22 23 7.6密码服务 设备的安全要求 45 8 8.1设备使用阶段 45 8.2权限管理 45 8.3密钥安全要求 46 8.4设备抗攻击要求 46 附录A规范性附录)错误代码定义和说明 47
GB/35291一2017 前 言 本标准依据GB/T1.1一2009给出的规则起草 请注意本文件的某些内容可能涉及专利 本文件的发布机构不承担识别这些专利的责任 本标准由全国信息安全标准化委员会(SAC/TC260)提出并归口 本标准起草单位:北京海泰方圆科技股份有限公司、北京握奇智能科技有限公司、北京大明五洲科 技有限公司、恒宝股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限公司、 北京飞天诚信科技股份有限公司、华翔腾数码科技有限公司 本标准起草人;刘平、郭宝安、石玉平、柳增寿、胡俊义、管延军,赵再兴、刘伟丰、何永福、李高锋、 汪雪林、赵李明、蒋红宇、王烨
GB/T35291一2017 引 言 本标准的目标是为公钥密码基础设施应用体系框架下的智能密码钥匙设备制定统一的应用接口标 准,通过该接口调用智能密码钥匙,向上层提供基础密码服务 为该类密码设备的开发、使用及检测提 供标准依据和指导,有利于提高该类密码设备的产品化、标准化和系列化水平 本标准未包含标识算法SM9相关的应用接口 IN
GB/35291一2017 信息安全技术 智能密码钥匙应用接口规范 范围 本标准规定了基于PKI密码体制的智能密码钥匙应用接口,描述了密码相关应用接口的函数、数 据类型、参数的定义和设备的安全要求 本标准适用于智能密码钥匙产品的研制、使用和检测 规范性引用文件 下列文件对于本标准的应用是必不可少的 凡是注日期的引用文件,仅注日期的版本适用于本文 件 凡是不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件 GB/T33560信息安全技术密码应用标识规范 GM/T0022IPSecVPN技术规范 GM/T0024ssLVPN技术规范 术语和定义 下列术语和定义适用于本文件 3.1 容器cntainer 密码设备中用于保存密钥所划分的唯一性存储空间 3.2 设备认证deyieeauthentication 智能密码钥匙对应用程序的认证 3.3 设备认证密钥deviceauthenticationkey 用于设备认证的密钥 3.4 设备标签lahel 由用户设定并存储于设备内部的用于对设备进行标识的字符串 缩略语 下列缩略语适用于本文件 API 应用编程接口(AppicationProgrammingInterface) MAC 消息鉴别码(MessageAuthenticeationCode' PIN 个人身份识别码(PersonalldentifieationNumber)
GB/T35291一2017 PKCS井1 公钥密码使用标准系列规范中的第1部分,定义RSA公开密钥算法加密和签名机制 thePublic-KeyCryptographyStandardPart1 PKCS#5公钥密码使用标准系列规范中的第5部分,描述一种利用从口令派生出来的安全密 钥加密字符串的方法(thePublic-KeyCryptographyStandardPart5) PKI 公钥基础设施(PublieKeylnfrastrueture) 5 结构模型 5.1层次关系 智能密码钥匙应用接口位于智能密码钥匙应用程序与设备驱动程序之间,如图1所示 智能密码钥匙应用程序 智能密码钥匙应用接口 智能密码钥匙设备驱动程序 设备2 .= 设备" 设备mm 图1接口在应用层次关系中的位置 5.2设备的应用结构 个设备中存在设备认证密钥和多个应用,应用之间相互独立 设备的逻辑结构如图2所示 设备认证密钥 应用 应用2 ## 应用n 图2设备逻辑结构 应用由管理员PIN、用户PIN,文件和容器组成,可以存在多个文件和多个容器 每个应用维护各自的与管理员PIN和用户PIN相关的权限状态 一个应用的逻辑结构如图3所示 容器中存放加密密钥对签名密钥对和会话密钥 其中加密密钥对用于保护会话密钥,签名密钥对 用于数字签名和验证,会话密钥用于数据加解密和MAC运算 容器中也可以存放与加密密钥对对应 的加密数字证书和与签名密钥对对应的签名数字证书 其中,签名密钥对由内部产生,加密密钥对由外 部产生并安全导人.会话密钥可由内部产生或者由外部产生并安全导人
GB/35291一2017 管理员PIN 加密公钥 签名公钥 容器1 加密私钥 签名私钥 用户PIN 会话密钥 会话密钥2 会话密钥k 文件 文件2 加密公钥 签名公钥 容器n 加密私钥 签名私钥 会话密钥 会话密钥2 会话密钥 文件m 图3应用逻辑结构图 数据类型定义 6.1算法标识 本标准中使用的算法其标识定义见GB/T3356o 6.2基本数据类型 本标准中的字节数组均为高位字节在前(Big-Endian)方式存储和交换 基本数据类型定义如表1 所示 表1基本数据类型 类型名称 描述 定义 NT8 有符号8位整数 INTl6 有符号16位整数 INT32 有符号32位整数 UINT8 无符号8位整数 无符号16位整数 UINTl6 UIVT32 无符号2位整数 BO(oL 布尔类型,取值为TRUE或FAL.sE BYTE edefUINT8BYTE 字节类型,无符号8位整数 yped CHAR 字符类型,无符号8位整数 DedefUINT8CHAR ype SHORT 短整数,有符号16位 typedefINTl6SHORT
GB/T35291一2017 表1续 类型名称 描述 定义 USHORT 无符号16位整数 typedefUINTl6USHORT LONG 长整数,有符号32位整数 typedefINT32LONG 长整数,无符号32位整数 UI.ONG typedefUINT32UL(ONG UINT 无符号32位整数 ypdeUINT32UINT wo)RD lefUINT16wORD 字类型,无符号16位整数 typede DwORD edefUINT32DwORD 双字类型,无符号32位整数 ypedl bedefUINT32FL.AGS FLAGS 标志类型,无符号32位整数 yp typedefCHAR*LPSTR LPSTR 8位字符串指针,按照UTF8格式存储及交换 HANDLE 句柄,指向任意数据对象的起始地址 typedefvoid着HANDLE DEVHANDLE 设备句柄 typedefHANDLEDEVHANDLE HAPPLICATlON 应用句柄 ypedefHANDLEHAPPLICATION fHANDL.EHcoTAIER HcONTAINER 容器句柄 ypede 6.3常量定义 数据常量标识定义了在规范中用到的常量的取值 数据常量标识的定义如表2所示 表2常量定义 常量名 取值 描述 TRUE 0x00000001 布尔值为真 布尔值为假 FALSE 0x00000000 DEvAP stdecall tdeall函数调用方式 ADMINTYPE 管理员PIN类型 USER_TYPE 用户PIN类型 6.4复合数据类型 6.4.1版本 6.4.1.1 类型定义 ypedef Struct_Version struct BYTEmajor; BYTEnminor VERSION, 6.4.1.2数据项描述 数据项描述见表3.
GB/35291一2017 表3版本定义 数据项 类型 意义 备注 BYTE major 主版本号 主版本号和次版本号以"."分隔,例如Vers ersionl.0,主版本号为l,次版本号 次版本号为0,version2.10.主版本号为2.次版本号为10 BYTE minor 6.4.2设备信息 6.4.2.1 类型定义 structStructDEVINFO ypede、 VERSION Version; CHAR Manufacturer[64钉; CHAR Issuer[64]; CHAR Label[32]; SerialNumber[32]; CHAR HWVersion; VERSIO N VERSION FirmwareVersion AlgSymCap; ULONNG ULoNc AlgAsymCap; L.ONG AlgHHashCap; LONG DevAuthAlgld ULoNc TotaSpace; ULONG FreeSpace; ULoNc MaxECCBufferSize; ULONG MaxBufferSize; BYTE Reserved[64]; DEVINFo_SKF，*PDEVINFo_SKF 6.4.2.2数据项描述 数据项描述见表4 表4设备信息描述 意义 备注 数据项 类型 Version VERSION 版本号 数据结构版本号,本结构的版本号为1.0 Manufacturer CHAR数组 设备厂商信息 以'\0'为结束符的ASCI字符串 CHAR数组 发行厂商信息 以‘\0'为结束符的AsCI字符串 Issue CHAR数组 设备标签 以'\0'为结束符的AsC字符串 L.abel SerialINumber CHAR数组 序列号 以\0'为结束符的AsCI字符串 HwVersion VERSION 设备硬件版本 FirmwareVersion VERSION 设备本身固件版本
GB/T35291一2017 表4续 数据项 类型 意义 备注 AlgSymCap UL(ONG 分组密码算法标识 AlgAsymCap ULONG 非对称密码算法标识 AlgHasCap U1ONG 密码杂凑算法标识 设备认证使用的分组密码算法 DevAuthAlgld UL.ONG 标识 TotalSpace UL(ONG 设 备总空间大小 UL(ONG 用户可用空间大小 FreeSpace MaxECCBufferSize UL(ONG 能够处理的CC加密数据大小 能够处理的分组运算和杂凑运 MaxBufferSize UL(oNG 算的数据大小 BYT 保留扩展 Reserved 6.4.3RSA公钥数据结构 6.4.3.1 类型定义 pedefstructStruct_RSAPUBLICKEYBLOB yp ULONGAlgID; ULONGBitLe L.en; BYTEModulus[MAX_RSA_MODULUS_LEN] BYTEPublieExponent[MAX_RSA_EXPONENT_LEN]; RSAPUBL.ICKEYBLOB，*PRsAPUBLlICKEYBLOB; 其中,MAx_RSA_MODULUs_LEN为算法模数的最大长度;MAx_RsA_EXPONENT_LEN为 算法指数的最大长度 6.4.3.2数据项描述 数据项描述见表5 表5RSA公钥数据结构 数据项 类型 意义 备注 算法标识号 AlglD UL(ONG Bitl.en UL(ONG 应为8的倍数 模数的实际位长度 实际长度为Bitl.en/8字节 BYTE数组 模数n=p"9 Modulus 井defineMAX_RSA_MODULUS_LEN256 #defineMAX_RSA_EXPONENT_LEN4 PublieExponent BYTE数组 公开密钥e -般为00010001
GB/35291一2017 6.4.4RSA私钥数据结构 6.4.4.1 类型定义 structStr ypedef truct_RsAPRIVATEKEYBL.OB0 ULONGAlgID, UL.ONGBitL.en; BYTEModulus[MAx_RsA_MODULUS_LEN]; BYTEPublieExponent[MAX_RSA_EXPONENT_LEN]; BYTEPrivateExponent[MAx_RsA_MODULUs_LEN] BYTEPrimel[MAx_RsA_MODULUs_LEN/2]; BYTEPrime2[MAx_RsA_MODULUs_LEN/2]; BYTEPrimelExponent[MAX_RSA_MODULUs_LEN/2] BYTEPrime2Exponent[MIAx_RsA_MODULUs_LEN/2] BYTECoeffeient[MAx_RsA_MODULUsLE/2] }RSAPRIVATEKEYBLOB，关PRSAPRIVATEKEYBL(OB; 其中,MAX_RSA_MODUIUS_LEN为算法模数的最大长度;MAX_RSA_EXPONENT_LEN为 算法指数的最大长度 6.4.4.2数据项描述 数据项描述见表6 表6RsA私钥数据结构 数据项 类型 意义 备注 AgID UL(ONG 算法标识号 应为8的倍数 BitLen UL(ONG 模数的实际位长度 Moduls BYTE数组 模数n=p#g 实际长度为BitLl.en/8字节 PublieExponent BYTE数组 公开密钥e -般为00010001 实际长度为Bitlen/8字节 PrivateExponent BYTE数组 私有密钥d BYTE数组 素数p 实际长度为BBitl.en/16字节 Primel BYTE数组 素数q 实际长度为itl.en/16字节 Prime2 PrimelExponent BYTE数组 modp-1)的值 实际长度为Bitl.en/16字节 d Prime2Exponent BYTE数组 dmodq-1)的值 实际长度为Bitl.en/16字节 Coeffiecient BYTE数组 q模p的乘法逆元 实际长度为BitL.en/16字节 6.4.5CC公钥数据结构 6.4.5.1 类型定义 typedefstructsirueEcCPUBL.IcCKEYBL.oB ULONGBitLen BYTEXCoordinate[ECC_MAX_XcOORDINATE_BITs_LEN/8];
GB/T35291一2017 BYTEYCoordinate[EEcC_MAX_YcooRDINATE_BITs_LEN/8] ECCPUBLICKEYBLOB，关PECCPUBLICKEYBLOB 其中,EECC_MAX_XCOORDINATE_LEN为ECC算法X坐标的最大长度;ECC_MAX_YCOOR- DINATE_LEN为RCC算法Y坐标的最大长度 6.4.5.2数据项描述 数据项描述见表7 表7Ecc公钥数据结构 数据项 类型 意义 备注 Bitl.en ULONG 模数的实际位长度 应为8的倍数 有限域上的整数 曲线上点的X坐标 XCoordinate BYTE数组 井defineECC_MAX_XCOORDINATE_BITs_LEN512 有限域上的整数 YCoordinate BYTE数组 曲线上点的Y坐标 Ecc_MAx_YcooRDINATE_HTs_LEN512 井define 6.4.6ECC私钥数据结构 6.4.6.1 类型定义 typedefstructStruct_ECCPRIVATEKEYBLOB ULONGBitLen; BYTEPrfivatekey[Ecc_MAx_MoDUIUs_BITs_LEN/8] ECCPRIVATEKEYBLOB.关PEcCPRIVATEKEYBL.OB; 其中,ECC_MAx_MODULUS_BITS_LEN为ECC算法模数的最大长度 6.4.6.2数据项描述 数据项描述见表8 表8ECC私钥数据结构 数据项 类型 意义 备注 Bitl.en U1(ONG 模数的实际位长度 应为8的倍数 有限域上的整数 BYTE数组 私有密钥 PrivateKey 井defineBcc_MAx_MoDULUs_BITs_LEN512 6.4.7cC密文数据结构 6.4.7.1类型定义 typedefstructStruet_EccCIPHERBLOB BYTEXCoordinate[ECC_MAX_XcoORDINATE_BITS_LEN/8]; BYTEYCoordinate[EEcC_MAX_XCoORDINATE_BITs_LEN/8]; BYTEHASH[32];
GB/35291一2017 ULONGCipherlLen; BYTECipher[1] ECCCIPHERBLOB，关PECCCIPHERBLOB; 6.4.7.2数据项描述 数据项描述见表9 表9ECC密文数据结构 类型 意义 数据项 备注 XCoordinate BYTE数组 与y组成椭圆曲线上的点(x,y) YCoordinate BYTE数组 与x组成椭圆曲线上的点xy HASH BYTE数组 明文的杂凑值 Cipherl.en ULONG 密文数据长度 BYTE 密文数据 实际长度为CipherHlen Cipher 数组 6.4.8cC签名数据结构 6.4.8.1类型定义 )edefstructStr ECCSIGNATUUREBLOB type ruct_ BYTE[ECC_MAX_XCOORDINATE_BITS_LEN/8] BYTEs[ECC_MAX_XCOoORDINATE_BITs_LEN/8]; }ECCIGNATUREBLOB，关PECCSIGNATUREBLOB 其中,ECC_MAX_XCOORDINATE_BITs_LEN为ECC算法X坐标的最大比特长度 6.4.8.2数据项描述 数据项描述见表10 表10Ecc签名数据结构 数据项 类型 意义 备注 BYTE数组 签名结果的r部分 BYTE数组 签名结果的s部分 6.4.9分组密码参数 6.4.9.1类型定义 ypedefstruetStruct_BLOcCKCIPHERPARAM6 BYTEIV[MAx_IV_LEN]; ULONGIVLe .en: UILONGPaddingType; UL.ONGFeedBitl.en; BL.(OCKCIPHERPARAM,*PBLOCKCIPHERPARAM;
GB/T35291一2017 6.4.9.2数据项描述 数据项描述见表11 表11分组密码参数 数据项 类型 意义 备注 初始向量,MAx_IV_LEN为初始化向量的最大长度 v BYTE数组 井defineMAX_IV_LEN32 IVlen U1LONG 初始向量实际长度(按字节计算 填充方式,0表示不填充，1表示按照PKcS#5方式进 PaddingType UL(ONG 行填充 反馈值的位长度(按位计算 只针对oFB.CFB模式 FeedBitlen UILONG 6.4.10Ecc加密密钥对保护结构 6.4.10.1类型定义 ypedefstructsSKF_ENVELOPEDKEYBLOB UILONGVersion; ULONGulSymmAlgID; ULONGulBits; BYTEcbEncryptedPriKey[64] ECCPUBLICKEYBL.OBPubKey; EccCIPHERBLOBEccCipherBlob ENVELOPEDKEYBL.OB,*PENVELOPEDKEYBLOB: 私钥密文结构中64字节,有效密文分组从0偏移量字节开始,顺序解密密文分组后将明文连接得 到加密密钥对的私钥的明文 6.4.10.2数据项描述 数据项描述见表12 表12加密密钥对保护结构参数 数据项 类型 意义 备注 Version UL(ONG 版本号,本版本为1 ulSymmAlgID UL(ONG 对称算法标识 应为ECB模式 ulBits UL(ONG 加密密钥对的密钥位长 对称算法加密的加密私钥,加密私钥的 其有效长度为原文的 原文为EccCPRIVATEKEYBL.oB结构 cbEneryptediPnivKey BYTE数组 ulBits十7/8 中的PrivateKey RcCPUBLICKEYBLoB PK" 加密密钥对的公钥 EcCCIPHERBL.OB EccCipherlBob 用保护公钥加密过的对称密钥密义 10
GB/35291一2017 6.4.11文件属性 6.4.11.1 类型定义 ypedel struetStrucet_FIEATTRIBUTE CHARFileName[32] UL.ONGFileSize:; ULONGReadRights; ULONGwriteRights; FILEATTRIBUTE，关PFIIEATTRIBUTE: 6.4.11.2数据项描述 数据项描述见表13 表13文件属性 数据项 类型 意义 备注 FileName CHAR数组 文件名 以\0'结束的ASCI字符串,最大长度为32 FleSize UL(ONG 文件大小 创建文件时定义的文件大小 UL.oNG 读取权限 读取文件需要的权限 ReadRights ULONG 写人权限 写人文件需要的权限 writeRights 6.4.12权限类型 权限类型的定义见表14 表14权限类型 权限类型 值 说明 SECURE_NEVER_ACCoUNT 0x00000000 禁用 SECURE_ADM_ACCOUNT 0x00000001 管理员权限 SECURE_USER_ACCOUNT 0x00000010 用户权限 sEcURE_AYoNE_AccoUNT 任何人 0x000000FF 6.4.13设备状态 设备状态的定义见表15 表15设备状态 值 设备状态 说明 0x00000000 DEV_ABSENT_STATE 设备不存在 DEV_PRESENT_STATE 0x00000001 设备存在 DEV_UNKNOw_STATE 0x00000002 设备状态未知 1
GB/T35291一2017 接口函数 7.1设备管理 7.1.1概述 设备管理主要完成设备的插拔事件处理、枚举设备、连接设备、断开连接、获取设备状态、设置设备 标签、获取设备信息,锁定设备,解锁设备和设备命令传输等操作 设备管理系列函数如表16所示 表16设备管理系列函数 函数名称 功能 SKF_waitForDevEwent 等待设备插拔事件 SKF_CanceIwaitForDevEvent 取消等待设备插拔事件 SKF_EnumDev 枚举设备 SKFConneetDev 连接设备 SKF_DisconnectDev 断开连接 获取设备状态 SKF_GetDevState sKF_SetLabel 设置设备标签 SKFGetDevlnfo 获取设备信息 SKFl.ockDev 锁定设备 SKF_UnlockDev 解锁设备 SKF_Transmit 设备命令传输 设备管理函数可能返回的错误码见附录A 7.1.2等待设备插拔事件 原型 UL.oNGDEVAPsKF_waitForDerEvenr(LPsTRsDeName,UL.oNG*pulDew NameLen,ULONG关pulE vent 功能描述该函数等待设备插人或者拔除事件 szDewName返回发生事件的设备名称 参数 [[oUT]发生事件的设备名称 szDevName pulDevNamelen [[IN/OUT输人/输出参数,当输人时表示缓冲区长度,输出时表示设 备名称的有效长度,长度包含字符串结束符 [oUT]事件类型 1表示插人,2表示拔出 pulEvent 返回值 SAR_OK: 成功 其他 错误码 注:本函数为阻塞函数 7.1.3取消等待设备插拔事件 原型 UIONGDEVAP1SKF_CanceWaitForDevEvent(O 功能描述该函数取消等待设备插人或者拔除事件 参数 12
GB/35291一2017 返回值 SAR_OK 成功 其他 错误码 注:使本进程正在执行的SKF_WaitForDevEvent函数立即返回 7.1.4枚举设备 UIONG;DEVAPIsKFEnumnDev(oO儿.bPresent,ILPsTRszNameList,UI.ONG*pulsize) 原型 功能描述获得当前系统中的设备列表 [IN]为TRUE表示取当前设备状态为存在的设备列表 为FALsE表示 参数 bPresent 取当前驱动支持的设备列表 [oU]设备名称列表 如果该参数为NULL将由pulsie返回所需要的 szNameList 内存空间大小 每个设备的名称以单个\0’结束,以双\0'表示列表的 结束 [[IN,OUT]输人时表示设备名称列表的缓冲区长度，输出时表示 pulSize szNameList所占用的空间大小 返回值 SAR_OK 成功 其他 错误码 7.1.5连接设备 原型 ULONGDEVAPIsKF_ConnectDev(LPSTRszName,DEVHANDLE关phDev 功能描述通过设备名称连接设备,返回设备的句柄 参数 [N]设备名称 szName [CoUT]返回设备操作句柄 phDev 返回值 sAR_OK 成功 其他 错误码 7.1.6断开连接 原型 ULONGDEVAPIsKF_DisConnectDev(DEVHANDLEhDev) 功能描述断开一个已经连接的设备,并释放句柄 参数 hDevy CIN]连接设备时返回的设备句柄 返回值 sAR_OK 成功 其他 错误码 注，如果该设备已被锁定,丽数应首先解锁该设备 断开连接操作并不影响设备的权限状态 7.1.7获取设备状态 *pulDevState) 原型 ULONGDEVAPISKF_GetDevState(LPSTRszDevName,ULONG 功能描述获取设备是否存在的状态 szDevName 参数 [IN]设备名称 pulDeSt [OUT]返回设备状态 State 返回值 sAR_OK: 成功 其他 错误码 7.1.8设置设备标签 原型 UI.ONGDEVAPISKF_SetL.abel(DEVHANDLEhDev,L.PSTRszLabel 13

GB/35291一2017 7.2访问控制 7.2.1概述 访问控制主要完成设备认证、PIN码管理和安全状态管理等操作 访问控制系列函数如表17 所示 表17访问控制系列函数 丽数名称 功能 SKF_ChangeDevAuthKey 修改设备认证密钥 SKF_DevAuth 设备认证 SKF_ChangePIN 修改PIN 获得PIN码信息 SKF_GetPINInfo PIN KF_VerifyPIN 校验1 sRKE_Unbie ckPI 解锁PIN SKF_ClearSecueState 清除应用安全状态 访问控制函数可能返回的错误码见附录A 7.2.2修改设备认证密钥 原型 UL.ONGDEVAPISKF_ChangeDevAuthKey(DEVHANDLEhDev,EBYTE关pbKeyVaue, ULONGulKeyLen) 功能描述更改设备认证密钥 参数 hDev [IN]连接时返回的设备句柄 pbKeyValue [IN]密钥值 [IN]密钥长度 ulKeyLen 返回值 SAR_OK 成功 其他 错误码 注:权限要求;设备认证成功后才能使用 7.2.3设备认证 原型 UI.ONGDEVAPIsKF_DevAuth(DEVHANDLEhDev,BYTE*pbAuthData,UI.ONG ulLen 功能描述设备认证是设备对应用程序的认证 认证过程参见8.2.3 参数 hDev [IN]连接时返回的设备句柄 [IN]认证数据 pbAuthData IN]认证数据的长度 ulLen SAR_OK 返回值 成功 其他 错误码 7.2.4修改PIN 原型 UIONGDEVAPSKF_ChangePIN(HAPPLICATIONhApplication,UL.ONGulPINType,LP 15
GB/T35291一2017 STRszOdPn,LPSTRsNewPin,ULONG*pulRetryCount) 功能描述调用该函数可以修改AdministratorPIN和UserPIN的值 如果原PIN码错误导致验证失败,该函数会返回相应PIN码的剩余重试次数,当剩余次数 为0时,表示PIN已经被锁死 参数 hApplicat tion [IN]应用句柄 ulPINType [IN]PIN类型,可为ADMIN_TYPE或USER_TYPE szOldPin [IN]原PIN值 szNewPin [IN]新PIN值 pulRetryCount[oU出错后重试次数 SAROK 返回值 成功 其他: 错误码 7.2.5获取PIN信息 原型 ULONGDEVAPSKF_GetPINInfo(HAPPLICATIONhApplieation,UIONGlPINIype,UL- ONG关pulMaxRetryCount,UIONG*pulIRemainRetryCount,BOOL 关pbDefaultPin) 获取PIN码信息,包括最大重试次数、当前剩余重试次数,以及当前PIN码是否为出厂默认 功能描述 PIN码 [IN]应用句柄 参数 hApplication [IN]PIN类型 ulPINType [[oUT]最大重试次数 pulMaxRetryCount [oUT]当前剩余重试次数,当为0时表示已锁死 pulRemainRetryCount [[oUT]是否为出厂默认PIN码 pbDefaultPin 返回值 SAR_OK: 成功 其他 错误码 7.2.6校验PIN 原型 UONGDEVAPSKF_VerifyPIN(HAPPLICATIONhApplieation,UIONGlPINIype" LPSTRszPIN,UL.(ONG关pulRetryCount 功能描述校验PIN码 校验成功后,会获得相应的权限,如果PIN码错误,会返回PIN码的重试次 数,当重试次数为0时表示PIN码已经锁死 参数 hApplieation [IN]应用句柄 ulPINType [IN]PIN类型 szPIN [[IN]PIN值 pulRetryCount[OUT出错后返回的重试次数 返回值 SAR_OK 成功 其他: 错误码 7.2.7解锁PIN 原型 ULONGDEVAPISKF_UnblockPINHAPPLICATIONhAppliceation,LPSTRszAdmin- 2N PIN,LPsSTRs2 ewUserPIN,ULONG关pulRetryCount) 功能描述当用户的PIN码锁死后,通过调用该函数来解锁用户PIN码 解锁后,用户PIN码被设置成新值,用户PIN码的重试次数也恢复到原值 参数 hApplieation [IN]应用句柄 16
GB/35291一2017 szAdminPIN [IN]管理员PIN码 szNewUserPIN[IN]新的用户PIN码 pulRetryCount[OUT管理员PIN码错误时,返回剩余重试次数 返回值 sAR_OK: 成功 其他 错误码 注:验证完管理员PIN才能够解锁用户PIN码,如果输人的AdministratorPIN不正确或者已经锁死,会调用失败 并返回AdministratorPIN的重试次数 7.2.8清除应用安全状态 ULONGDEVAPIsKF_ClearSeeureState(HAPPLICATIOoNhApplication) 原型 功能描述清除应用当前的安全状态 参数 hApplication[IN]应用句柄 返回值 SAR_OK. 成功 其他 错误码 7.3应用管理 7.3.1概述 应用管理主要完成应用的创建、枚举、删除、打开、关闭等操作 应用管理系列函数如表18所示 表18应用管理系列函数 函数名称 功能 sKF 创建应用 _CreateAppliecation sKF_Enum.Applieationm 枚举应用 SKFDeleteApplication 删除应用 SKF_OpenApplication 打开应用 SKF_CloseApplication 关闭应用 应用管理函数可能返回的错误码见附录A 创建应用 7.3.2 原型 UIOGDEVAP1sKF_CreateApplication(DEVHANDLEhDev,LPsTRszAppName LPsTRszAdminPin.DwORDdwAdminPinRetryCount.LPsTRszUserPin.DwORD dwUserPinRetryCount,DwORDdwCreateFileRights，HAPPLICATION*phApplica tion 功能描述创建一个应用 参数 hDev [IN]连接设备时返回的设备句柄 szAppName [IN]应用名称 szAdminPinm [IN]管理员PIN dwAdminPinRe RetryCount[IN]管理员PIN最大重试次数 szUserPin [[IN]用户PIN [N]用户PIN最大重试次数 dwUserPinRetryCo ount dwCreateFileRights [IN]在该应用下创建文件和容器的权限,参见6.4.9权限类型 17
GB/T35291一2017 为各种权限的或值 phApplieation [[OUT]应用的句柄 返回值 SAR_OK: 成功 其他 错误码 注;权限要求;需要设备权限 7.3.3枚举应用 原型 ULONGDEVAPISKF_EnumApplieation(DEVHANDLEhDev,LPSTRszAppName ULONG*pulSize 功能描述枚举设备中存在的所有应用 参数 hDev [IN]连接设备时返回的设备句柄 szAppName[OUT返回应用名称列表,如果该参数为空,将由pulSize返回所需要的内 存空间大小 每个应用的名称以单个\0'结束,以双'\0'表示列表的结束 [IN,oUT输人时表示应用名称的缓冲区长度,输出时返回szAppNanme所 Dulsize 占用的空间大小 返回值 SAR_OK 成功 其他 错误码 7.3.4删除应用 原型 ULoNGDEvAPsKF_DleeApp plieation(DEVHANDLEhDev,LPSTRszAppNa ame 功能描述删除指定的应用 参数 Dev [IN]连接设备时返回的设备句柄 zApName[IN]应用名称 返回值 SAR_OK 成功 其他: 错误码 注，权限要求;需要设备权限 7.3.5打开应用 原型 ULoNGDEVAPIsKF_OpenApplication(DEVHANDLEhDev,LPsTRszAppName HAPPLlICATION*phApplication) 功能描述打开指定的应用 参数 hDe [IN]连接设备时返回的设备句柄 zAppNa [IN]应用名称 ame phApplieatio [[OUT]应用的句柄 1On 返回值 SAR_OK: 成功 其他 错误码 7.3.6关闭应用 原型 ULONGDEVAPSKF_CloseApplication(HAPPLICATIONhApplication) 功能描述关闭应用并释放应用句柄 参数 hApplication [IN]应用句柄 返回值 SAR_OK: 成功 其他 错误码 注;此丽数不影响应用安全状态 18

GB/T35291一2017 7.4.4枚举文件 原型 ULONGDEVAPISKF_EnumFilesHAPPLICATIONhApplication,LPSTRszFileList, ULONG *pulsuze) 功能描述枚举一个应用下存在的所有文件 参数 hApplieat [IN]应用句柄 tion s2zFileList [OUT]返回文件名称列表,该参数为空,由pulSize返回文件信息所需要 的空间大小 每个文件名称以单个\0’结束,以双'\0’表示列表的结束 Dulsize [[IN,OUT输人时表示数据缓冲区的大小,输出时表示实际文件名称列 表的长度 SAR_OK 返回值 成功 其他: 错误码 7.4.5获取文件属性 原型 UIONGDEVAPISKF_GetFilelnfo(HAPPLICATIONhApplication,LPSTRzFileNamme,FII- EATTRIBUTE*pFilenfo 功能描述获取文件信息 获取应用文件的属性信息,例如文件的大小、权限等 参数 hApplieation[IN]文件所在应用的句柄 szFileName [IN]文件名称 [oU]文件信息,指向文件属性结构的指针 pFilelnfo 返回值 SAR_OK: 成功 其他 错误码 7.4.6读文件 原型 ULONGDEVAPISKF_ReadFile(HAPPLlICATIONhApplieation,LPSTRszFileName UL.ONGuloffset,ULONGulSize,BYTE*pbOutData,ULONG关pulOutLen) 功能描述读取文件内容 [IN]应用句柄 参数 hApplication [IN]文件名 szFileName uoffset [IN]文件读取偏移位置 [IN]要读取的长度 uSize [OUT返回数据的缓冲区 pbOutData [IN,OUT]输人时表示给出的缓冲区大小;输出时表示实际读取返回的数 pulOutlenm 据大小 返回值 SAR_OK 成功 其他 错误码 注权限要求;须具备对该文件的读权限 7.4.7写文件 OE cation,LPSTRszFileName 原型 UL.ONGDEVAPISKF_writeFileHAPPLICATIONhApp UL.ONGulOfset,BYTE*pbData,U.ONGulSize' 功能描述写数据到文件中 20
GB/35291一2017 参数 hApplication [IN]应用句柄 zFileName [[IN]文件名 ulofset [IN]写人文件的偏移量 pbData [IN]写人数据缓冲区 ulSize [IN]写人数据的大小 返回值 SAR_OK: 成功 其他 错误码 注权限要求;须具备该文件的写权限 7.5容器管理 7.5.1概述 本标准提供的应用管理用于满足各种不同应用的管理,包括创建、删除、枚举、打开和关闭容器的操 作 容器管理系列函数如表20所示 表20容器管理系列函数 丽数名称 功能 SKF_CreateContainer 创建容器 SKF_DeleteContainer 删除容器 SKF_EnumContainer 枚举容器 打开容器 SKFOpenContainer SKFCloseContainer 关闭容器 SKF_GetContainerType 获得容器类型 SKF_ImportCertifieate 导人数字证书 SKF_ExportCertificate 导出数字证书 容器管理函数可能返回的错误码见附录A 7.5.2创建容器 原型 UIONGDEVAPISKF_CreateContainerHAPPLICATIONhApplieation,LPSTRsxCon- tainerName,HCONTAINER*phCo ontainer 功能描述在应用下建立指定名称的容器并返回容器句柄 参数 hApplieat [[IN]应用句柄 ation szContainerName IN]AsCI字符串,表示所建立容器的名称,容器名称的最大长度不 能超过64字节 [OUT]返回所建立容器的容器句柄 phContainer 返回值 SAR_OK: 成功 其他: 错误码 注:权限要求;需要用户权限 7.5.3删除容器 原型 UL.ONGDEVAPIsSKF_DeleteContainer(HAPPLICATIONhApplication,LPsTRszCon 21
GB/T35291一2017 tainerName 功能描述在应用下删除指定名称的容器并释放容器相关的资源 参数 hApplication [IN]应用句柄 szContainerName [IN]指向删除容器的名称 返回值 SAR_OK: 成功 其他: 错误码 注:权限要求;需要用户权限 7.5.4打开容器 原型 ULONGDEVAPIsSKF_OpenContainer(HAPPLICATIONhApplieation,LPSTRsxCon- tainerNanme,HcONTAINER*phContainer) 功能描述获取容器句柄 参数 [[IN]应用句柄 hApplication [IN]容器的名称 szContainerName [[oUT]返回所打开容器的句柄 phContainer 返回值 SAR_OK. 成功 其他 错误码 7.5.5关闭容器 原型 ULONGDEVAPSKF_CloseContainer(HCONTAINERhContainer) 功能描述关闭容器句柄,并释放容器句柄相关资源 参数 hContainer [IN]容器句柄 返回值 SAR_OK. 成功 其他 错误码 7.5.6枚举容器 原型 ULONGDEVAPISKF_EnumContainer(HAPPLICATIONhApplieation,LPSTRsz/Con- tainerName,ULONG关pulSize) 功能描述枚举容器下所有容器并返回容器名称列表 参数 hApplication [[IN]应用句柄 szxContainerName [OUT指向容器名称列表缓冲区,如果此参数为NULL时,pulSize 表示返回数据所需缓存区的长度,如果此参数不为NULL时,返回容 器名称列表,每个容器名以\0'为结束,列表以双'\0'结束 pulsie [IN,OUT]输人时表示szContainerName缓存区的长度,输出时表示 容器名称列表的长度 返回值 SAR_OK. 成功 其他: 错误码 7.5.7获得容器类型 rype(HcoNTAINERhcon ontainer,ULONG 原型 UILONGDEVAPISKF_GetContainerT ”pul ContainerType) 功能描述获取容器的类型 Container 参数 [IN]容器句柄 22
GB/35291一2017 puca rType[OUT]获得的容器类型 指针指向的值为0表示未定、尚未分配类型 ontainer 或者为空容器,为1表示为RSA容器,为2表示为SM2容器 返回值 SAR_OK: 成功 其他 错误码 7.5.8导入数字证书 原型 UONGDEVAPISKF_lmportCertifieate(HCONTAINERhContainer,B0OLbSignFlag BYTE着pbCert,UL.ONGulCertL. en 功能描述向容器内导人数字证书 hContainer 参数 [IN容器句柄 [IN]TRUE表示签名证书,FAL.sE表示加密证书 bSignFlag IN]指向证书内容缓冲区 pbCert ulCertLen IN证书长度 返回值 SAR_OK: 成功 其他 错误码 7.5.9导出数字证书 UL.ONGDEVvAPIsKF_ExportCertificate(HcONTAINERhContainer,B0oL.bSsignFlag 原型 BYTE*pbCert,ULONG关pulCertLen) 功能描述从容器内导出数字证书 [N]容器句柄 参数 hContainer [IN]TRUE表示签名证书,FAL.SE表示加密证书 bSignFlag [OUT指向证书内容缓冲区,如果此参数为NUIL时,pulcCertl.en表示返 pbCert 回数据所需要缓冲区的长度,如果此参数不为NULL时,返回数字证书 内容 [IN/OUT]输人时表示pbCert缓冲区的长度,输出时表示证书内容的 pulCertLen 长度 返回值 SAR_OK 成功 其他 错误码 7.6密码服务 7.6.1概述 密码服务函数提供对称算法运算、非对称算法运算、密码杂凑运算、密钥管理、消息鉴别码计算等功 能 密码服务系列函数如表21所示 表21密码服务系列函数 函数名称 功能 SKF_GenRandom 生成随机数 SKFGenExtRSAKe 生成外部RsA密钥对 Key SKF_GenRSAKeyPair 生成RsA签名密钥对 SFIn brtRsAKeyPair 导人RSA加密密钥对 mport 23
GB/T35291一2017 表21(续 丽数名称 功能 SKF_RSASignData RSA签名 sKF_RSAVeris RSA验签 SKFRSAExportSessionkey RSA生成并导出会话密钥 SKF_ExtRSAPubKeyOperation RSA外来公钥运算 SKF_ExtRSAPriKeyOperation RSA外来私钥运算 SKF_GenCCKeyPair 生成ECC签名密钥对 SKF_lmportECCKeyPair 导人ECC加密密钥对 签名 ECC SKF_CCSignData KFBCCVerlsy Ecc验签 SKFECCExportSessionkey EcC生成并导出会话密钥 SKF_ExtEcCEncrypt EcC外来公钥加密 SKFExtECCDecrypt ECC外来私钥解密 SKF_ExtECCSign ECC外来私钥签名 BcC外来公钥验签 SKF_ExtECCVerify Ecc生成密钥协商参数并输出 SKF_GenerateAgreementDataWithCC SKFGenerateKeywithEcc Ecc计算会话密钥 SKFGenerateAgreementDataAndKeywithECC ECC产生协商数据并计算会话密钥 SKF_GenerateKeywithIKE 计算IKE工作密钥 SKF_GeneratekKeywithEPK_IKE 计算IKE工作密钥并用外部公钥加密导出 SKF_GenerateKeywithIPSEC 计算IPSEC会话密钥 SKF_GenerateKeywithEPK_IPSEC 计算IPSEC会话密钥并用外部公钥加密导出 SKF_GeneratekKeywithSSL 计算SSL工作密钥 withEPKssL sKF_Generatekeywi 计算ssL.工作密钥并用外部公钥加密导出 SKF_ExportPublieKey 导出公佣 SKF_ImportSessionkey 导人会话密钥 SKF_SetSymmKey 明文导人会话密钥 SKF_Eneryptlnit 加密初始化 SKF_Enerypt 单组数据加密 SKF_EneryptUpdate 多组数据加密 Ae SKF ina 结束加密 -EBmcyt 解密初始化 sKF_Deryplnit SKF_Dec 单组数据解密 ccrypt SKF_DeeryptUpdate 多组数据解密 SKF_DecryptFinal 结束解密 24
GB/35291一2017 表21(续 函数名称 功能 SKF_Digesli 密码杂凑初始化 SKF_Digest 单组数据码杂凑 多组数据密码杂凑 SKF_DigestUpdate SKF_DigestFinal 结束密码杂凑 SKF_Maclnit 消息鉴别码运算初始化 SKF_Mac 单组数据消息鉴别码运算 sKF_MaeUpdate 多组数据消息鉴别码运算 sKF_MacFinal 结束消息鉴别码运算 SKF_CloseHandle 关闭密码对象句柄 密码服务函数可能返回的错误码见附录A 7.6.2生成随机数 ULONGDEVAPISKF_GenRandom(DEVHANDLEhDev,BYTE关pbRandom,ULONG 原型 ulRandoml.en) 功能描述产生指定长度的随机数 参数 hDev [IN]设备句柄 pbRandom [OUT]返回的随机数 ulRandoml [IN]随机数长度 en 返回值 SAR_OK: 成功 其他 错误码 7.6.3生成外部RSA密钥对 原型 UL.ONGDEVAPISKF_GenExtRSAKey(DEVHANDLEhDev,UL.ONGulBitsLen,RsA PRIVATEKEYBLOB*pBlob) 由设备生成RsA密钥对并明文输出 功能描述 参数 hDev ON]设备句柄 [IN]密钥模长 ulBitslen [oUT]返回的私钥数据结构 pBlob 返回值 SAR_OK. 成功 其他: 错误码 注:生成的私钥只用于输出,接口内不做保留和计算 7.6.4生成RsA签名密钥对 原型 UIONGDEVAPsKF_GenRSAKeyPair(HcONTAINERhContainer,UONGulBitslen RSAPUBLICKEYBLOB关pBob 功能描述生成SA签名密钥对并输出签名公钥 hContainer 参数 [IN容器句柄 ulBitsLen [N]密钥模长 25
GB/T35291一2017 pBlob [OUT]返回的RSA公钥数据结构 SAROK 返回值 成功 其他: 错误码 注:权限要求;需要用户权限 7.6.5导入RSA加密密钥对 原型 ULOGDEVAPISKFImportRsAKeyPair HCONTAINERhContainer,UL(ONGulSymAlgld， BYTE*pbhwrppedkKey,UL.ONGwlwrtpelKelen. BYTE*pbEneryptedData,ULONG ulEncryp ptedDatalen 功能描述导人RSA加密公私钥对 [IN]容器句柄 参数 hContainer [IN uSymAlgld 对称算法密钥标识 [IN]使用该容器内签名公钥保护的对称算法密钥 pbWrappedKey [IN保护的对称算法密钥长度 ulWrappedKeyLen [IN对称算法密钥保护的RsA加密私钥 私钥的格式遵循PKs pbEneryptedData #lv2.1:RSACryptographyStandard中的私钥格式定义 ulEneryptedDatal.en[IN]对称算法密钥保护的RSA加密公私钥对长度 返回值 SAR_OK: 成功 其他 错误码 注:权限要求:需要用户权限 7.6.6RSsA签名 原型 U1ONGDEVAISKF_RSASignData(HcONTAINERhContainer,BYTE*pbData,UI ONGulDataLen,BYTE关pbsignature,UL.ONG关pulSignl.en 功能描述使用hContainer指定容器的签名私钥,对指定数据pbData进行数字签名 签名后的结果 存放到pbSignature缓冲区,设置pulsignlen为签名的长度 参数 [IN]用来签名的私钥所在容器句柄 hContainer [IN]被签名的数据 pbData [IN]签名数据长度,应不大于RSA密钥模长-11 ulDatalen [OUT]存放签名结果的缓冲区指针,如果值为NUIL,用于取得签名结 pbSignature 果长度 pulSignlen [IN,OUT]输人时表示签名结果缓冲区大小,输出时表示签名结果长度 返回值 SAR_OK. 成功 其他 错误码 注，权限要求;需要用户权限 7.6.7RSA验签 原型 U1.ONGDEVAPISKF_RSAVerifyDEVHANDLEhDev,RSAPUBL.ICKEYBL.OB ure,ULONG RsAPrbKeytlaob,.BYTE"pbDn ata,ULONGulDataLen,BYTE*pbSignat ulSignl.e en 功能描述验证RsA签名 用pRSAPubKeyBlob内的公钥值对待验签数据进行验签 Dev 参数 [IN]设备句柄 26

信息安全技术智能密码钥匙应用接口规范GB/T35291-2017

一、规范的制定背景

随着互联网技术的飞速发展，人们对于信息安全的需求越来越强烈。在这种背景下，智能密码钥匙成为了现代信息安全保障的重要手段之一。然而，不同厂家生产的智能密码钥匙之间存在着互不兼容的情况，这给用户带来了很多不便。因此，国家标准化管理委员会组织相关专家编制了《信息安全技术智能密码钥匙应用接口规范GB/T35291-2017》，旨在规范智能密码钥匙的应用接口，提高其兼容性和安全性。

二、规范的主要内容

《信息安全技术智能密码钥匙应用接口规范GB/T35291-2017》的主要内容包括：

1. 术语和定义：对于本规范中所使用的术语进行了明确的定义。
2. 接口协议：规定了智能密码钥匙的应用接口协议，确保不同厂家生产的智能密码钥匙之间可以实现互联互通。
3. 数据格式：规定了智能密码钥匙与应用系统之间传输数据时所采用的格式，避免数据丢失或被篡改。
4. 应用场景：对于智能密码钥匙的应用场景进行了详细描述。

三、规范的应用前景

GB/T35291-2017规范的制定和推广将有利于提高智能密码钥匙的兼容性和安全性，加强信息安全保障。同时，规范的推广还将促进智能密码钥匙行业的健康发展，促进各厂家之间的合作与交流。

总结

信息安全技术智能密码钥匙应用接口规范GB/T35291-2017是智能密码钥匙领域的一项重要标准，其制定和推广将对提高信息安全保障水平、促进行业健康发展等方面产生积极影响。

信息安全技术智能密码钥匙应用接口规范的相关资料

和信息安全技术智能密码钥匙应用接口规范类似的标准