skf

package module
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 16, 2025 License: MIT Imports: 6 Imported by: 0

README

SKF（智能密码钥匙密码应用接口）

  • 终端设备（Dev）：例如USBKey

    • 出厂时预置 设备认证密钥；
    • 设备支持多个应用，且应用之间相互独立。

  • 应用（App）

    • App 由管理员PIN、用户PIN、文件、容器组成，可有多个文件和多个容器；
    • 创建和删除应用必须获得设备权限（设备认证-1.3 设备认证流程）；

  • 容器（Container）

    • 容器用于存放加密密钥对、签名密钥对、会话密钥；
    • 加密密钥对用于保护会话密钥，签名密钥对用于数字签名和验签，会话密钥用于数据加解密和 MAC 运算；
    • 签名密钥对由内部产生（GenECCKeyPair），加密密钥对由外部导入（ImportECCKeyPair）
    • 创建和删除容器必须获得用户权限（PIN验证）

1. 权限管理

1.1 权限分类

权限分为设备权限、用户权限、管理员权限

  • 设备权限：通过设备认证后获得设备权限；
  • 用户权限：用户 PIN 码验证通过后，获得用户权限，用户权限只作用于其所在的应用；
  • 管理员权限：管理员 PIN 码验证通过后，获得管理员权限，管理员权限只作用于其所在应用；
1.2 权限使用

权限的使用遵循以下要求。

  • 设备权限仅用于创建应用、删除应用和修改设备认证密钥。
  • 创建和删除容器应已取得用户权限。
  • 创建文件的权限在创建应用时指定。
  • 文件的读写权限在创建文件时指定。
  • 容器内私钥的使用应已取得用户权限。
  • 用户 PIN 码和管理员 PIN 码均具有最大重试次数，在创建应用时设定。当验证 PIN 码错误次数达到最大重试次数后，PIN 码即锁死。
  • 用户 PIN 码的解锁，应已取得管理员权限。
  • 用户 PIN 码的修改，应已取得用户权限，管理员 PIN 码的修改，应已取得管理员权限。
1.3 设备认证流程

应通过设备认证后才能在设备内创建和删除应用。

设备认证使用分组密码算法和设备认证密钥进行，认证流程如下。

  1. 被认证方调用SKF_GenRandom函数从设备中获取 8 字节随机数 RND，并用0x00将其填充至密码算法的分块长度，组成数据库D0；
  2. 被认证方对D0加密，得到加密结果D1，并调用SKF_DevAuth()，将D1发送至设备；
  3. 设备收到D1后，验证D1是否正确，正确则通过设备认证，否则设备将认证失败。

Documentation

Index

Constants

View Source 
const (
	MAX_RSA_MODULUS_LEN      = 512 // 算法模数的最大长度
	MAX_RSA_EXPONENT_LEN     = 4   // 算法指数的最大长度
	ECC_MAX_XCOORDINATE_LEN  = 512 // ECC算法X坐标最大长度
	ECC_MAX_YCOORDINATE_LEN  = 512 // ECC算法Y坐标最大长度
	ECC_MAX_MODULUS_BITS_LEN = 512 // ECC算法模数的最大长度
	MAX_IV_LEN               = 32  // 初始化向量的最大长度
)
View Source 
const (
	SECURE_NEVER_ACCOUNT  uint32 = 0x00000000 // 不准许
	SECURE_ADM_ACCOUNT    uint32 = 0x00000001 // 管理员权限
	SECURE_USER_ACCOUNT   uint32 = 0x00000010 // 用户权限
	SECURE_ANYONE_ACCOUNT uint32 = 0x000000FF // 任何人
)
View Source 
const (
	DEV_ABSENT_STATE  = 0x00000000 // 设备不存在
	DEV_PRESENT_STATE = 0x00000001 // 设备存在
	DEV_UNKNOWN_STATE = 0x00000002 // 设备状态未知
)
View Source 
const (
	TRUE  int32 = 0x00000001 // TRUE 对应 BOOL 类型
	FALSE int32 = 0x00000000 // FALSE 对应 BOOL 类型
)
View Source 
const (
	ADMIN_TYPE = iota // 管理员PIN类型
	USER_TYPE         // 用户PIN类型
)
View Source 
const (
	EVENT_INSERT uint32 = 1 // 插入事件
	EVENT_REMOVE uint32 = 2 // 拔出事件
)
View Source 
const (
	SM2_1 uint32 = 0x00020200
)

Variables

This section is empty.

Functions

func ChangeAdminPin 

func ChangeAdminPin(handle unsafe.Pointer, oldPin, newPin string) error

ChangeAdminPin 修改管理员PIN码

handle 应用句柄 oldPin 原PIN码 newPin 新PIN码

func ChangeUserPin 

func ChangeUserPin(handle unsafe.Pointer, oldPin, newPin string) error

ChangeUserPin 修改用户PIN码

handle 应用句柄 oldPin 原PIN码 newPin 新PIN码

func ClearApplicationSecurityStatus 

func ClearApplicationSecurityStatus(handle unsafe.Pointer) error

ClearApplicationSecurityStatus 清楚应用的安全状态

handle 应用句柄

func CloseApplication 

func CloseApplication(handle unsafe.Pointer) error

CloseApplication 关闭某个应用

handle 应用句柄

func CloseContainer added in v0.0.5 

func CloseContainer(cHandle unsafe.Pointer) error

CloseContainer 关闭某个容器

cHandle 容器句柄

func CreateApplication 

func CreateApplication(handle unsafe.Pointer, info *ApplicationInfo) (unsafe.Pointer, error)

CreateApplication 创建应用，并返回应用句柄

info 需要创建的应用的信息

func CreateContainer added in v0.0.5 

func CreateContainer(appHandle unsafe.Pointer, name string) (unsafe.Pointer, error)

CreateContainer 创建容器，并返回容器句柄

appHandle 应用句柄 name 容器名称

func CreateFile 

func CreateFile(handle unsafe.Pointer, info *FileInfo) error

CreateFile 在应用中创建文件

handle 应用句柄 info 文件信息

func DeleteApplication 

func DeleteApplication(handle unsafe.Pointer, appName string) error

DeleteApplication 删除设备中名称为 appName 的应用

handle 设备句柄 appName 应用名称

func DeleteContainer added in v0.0.5 

func DeleteContainer(appHandle unsafe.Pointer, cName string) error

DeleteContainer 删除应用中名称为 cName 的容器

appHandle 应用句柄 cName 容器名称

func DeleteFile 

func DeleteFile(handle unsafe.Pointer, filename string) error

DeleteFile 删除应用中名称为 filename 的文件

handle 应用句柄 filename 文件名称

func DeviceAuthentication 

func DeviceAuthentication(devHandle unsafe.Pointer, authenticationKey string) (err error)

DeviceAuthentication 生成设备认证数据并发送至设备进行设备认证 创建和删除应用之前必须要进行设备认证

devHandle 设备句柄 authenticationKey 设备预置的设备认证密钥

func DisConnectDevice 

func DisConnectDevice(handle unsafe.Pointer) error

DisConnectDevice 断开某个设备的连接

handle 设备句柄

func EnumerateApplication 

func EnumerateApplication(handle unsafe.Pointer) ([]string, error)

EnumerateApplication 枚举出设备中所有的应用

handle 设备句柄

func EnumerateContainer added in v0.0.5 

func EnumerateContainer(appHandle unsafe.Pointer) ([]string, error)

EnumerateContainer 枚举出应用中所有的容器

appHandle 应用句柄

func EnumerateDevice 

func EnumerateDevice(present bool) ([]string, error)

EnumerateDevice 枚举所有的设备

present 为 true 表示获取当前状态为存在的设备列表，false 表示获取当前驱动支持的设备列表

func EnumerateFile 

func EnumerateFile(handle unsafe.Pointer) ([]string, error)

EnumerateFile 枚举出应用中的所有文件

handle 应用句柄

func ExportCertificate added in v0.0.5 

func ExportCertificate(cHandle unsafe.Pointer, isSign bool) ([]byte, error)

ExportCertificate 导出数字证书

cHandle 容器句柄 isSign 是否是签名证书,false表示加密证书

func GetAdminPinInfo 

func GetAdminPinInfo(handle unsafe.Pointer) (*internal.PINInfo, error)

GetAdminPinInfo 获取应用的管理员PIN信息

handle 应用句柄

func GetDeviceState 

func GetDeviceState(name string) (uint, error)

GetDeviceState 获取名称为 name 的设备状态，返回值 0 表示状态未知 1 表示设备存在 2 表示设备不存在

func GetUserPinInfo 

func GetUserPinInfo(handle unsafe.Pointer) (*internal.PINInfo, error)

GetUserPinInfo 获取应用的用户PIN信息

handle 应用句柄

func ImportCertificate added in v0.0.5 

func ImportCertificate(cHandle unsafe.Pointer, isSign bool, cert []byte) error

ImportCertificate 导入数字证书

cHandle 容器句柄 isSign 是否是签名证书,false表示加密证书 cert 证书字节数字

func ImportECCKeyPair added in v0.0.6 

func ImportECCKeyPair(cHandle unsafe.Pointer, encKey *EnvelopedKeyBlob) error

ImportECCKeyPair 导入加密密钥对

func ImportFileFromDevice 

func ImportFileFromDevice(appName, filename, pin string) ([]byte, error)

ImportFileFromDevice 从设备中导入文件，并返回文件内容；只提供应用名、文件名、PIN码必要参数，无需关心其他操作

func LockDevice 

func LockDevice(handle unsafe.Pointer, timeout uint32) error

LockDevice 锁定某个设备，如果超时时间为无限等待，传入 skf.INFINITE_WAITING

handle 设备句柄 timeout 超时时间

func OpenApplication 

func OpenApplication(handle unsafe.Pointer, appName string) (unsafe.Pointer, error)

OpenApplication 打开名称为 appName 的应用，并返回应用句柄

handle 设备句柄 appName 应用名称

func OpenContainer added in v0.0.5 

func OpenContainer(appHandle unsafe.Pointer, cName string) (unsafe.Pointer, error)

OpenContainer 打开名称为 cName 的容器，并返回容器句柄

appHandle 应用句柄 cName 容器名称

func OpenDevice 

func OpenDevice() (unsafe.Pointer, error)

OpenDevice 打开设备，返回设备句柄，默认打开设备列表中的第一个

func OpenDeviceWithIndex 

func OpenDeviceWithIndex(index uint, devList []string) (unsafe.Pointer, error)

OpenDeviceWithIndex 打开设备列表中指定索引的设备，并返回设备句柄

index 设备列表索引 devList 设备列表

func ReadFile 

func ReadFile(handle unsafe.Pointer, filename string, offset, size uint32) ([]byte, error)

ReadFile 读取应用中名称为 filename 的文件

handle 应用句柄 filename 文件名 offset 文件读取偏移量 size 要读取长度

func SetDeviceLabel 

func SetDeviceLabel(handle unsafe.Pointer, label string) error

SetDeviceLabel 设置设备标签

handle 设备句柄 label 标签

func UnLockDev 

func UnLockDev(handle unsafe.Pointer) error

UnLockDev 解锁某个设备

handle 设备句柄

func UnLockPIN 

func UnLockPIN(handle unsafe.Pointer, adminPin, newUserPin string) error

UnLockPIN 解锁用户PIN

handle 应用句柄 adminPin 管理员PIN码 newUserPin 新的用户PIN码

func VerifyAdminPin 

func VerifyAdminPin(handle unsafe.Pointer, pin string) error

VerifyAdminPin 验证应用的管理员PIN码，获取管理员权限

handle 应用句柄 pin 管理员PIN码

func VerifyUserPin 

func VerifyUserPin(handle unsafe.Pointer, pin string) error

VerifyUserPin 验证应用的用户PIN码，获取用户权限

handle 应用句柄 pin 用户PIN码

func WriteFile 

func WriteFile(handle unsafe.Pointer, filename string, offset uint32, inData []byte) error

WriteFile 向应用中写入文件

handle 应用句柄 filename 文件名 offset 文件写入偏移位置 inData 写入的数据

Types

type ApplicationInfo 

type ApplicationInfo struct {
	Name               string // 应用名称
	AdminPin           string // 应用的管理员PIN码
	AdminPinRetryCount uint32 // 管理员PIN码最大重试次数
	UserPin            string // 应用的用户PIN码
	UserPinRetryCount  uint32 // 用户PIN码的最大重试次数
	CreateRights       uint32 // 该应用下创建文件和容器的权限
}

type BlockCipherParam 

type BlockCipherParam struct {
	IV         [MAX_IV_LEN]byte // 初始向量
	IVLen      uint32           // 初始向量实际长度
	FeedBitLen uint32           // 反馈值的位长度，只针对 OFB、CFB 模式
}

BlockCipherParam 分组密码参数

type DeviceInfo 

type DeviceInfo struct {
	Version          Version  // 版本号
	Manufacturer     [64]byte // 设备厂商信息
	Issuer           [64]byte // 发行厂商信息
	Label            [32]byte // 设备标签
	SerialNumber     [32]byte // 序列号
	HWVersion        Version  // 设备硬件版本
	FirmwareVersion  Version  // 设备本身固件版本
	AlgSymCap        uint32   // 分组密码算法标识
	AlgAsymCap       uint32   // 非对称密码算法标识
	AlgHashCap       uint32   // 密码杂凑算法标识
	DevAuthAlgId     uint32   // 设备认证时使用的分组密码算法标识
	TotalSpace       uint32   // 设备总空间大小
	MaxECCBufferSize uint32   // 能够处理的ECC加密数据大小
	MaxBufferSize    uint32   // 能够处理的分组运算和杂凑运算的数据大小
	Reserved         [64]byte // 保留扩展
}

DeviceInfo 设备信息

func GetDeviceInfo 

func GetDeviceInfo(handle unsafe.Pointer) (*DeviceInfo, error)

GetDeviceInfo 获取某个设备的设备信息

handle 设备句柄

type ECCCipherBlob 

type ECCCipherBlob struct {
	XCoordinate [ECC_MAX_XCOORDINATE_LEN / 8]byte
	YCoordinate [ECC_MAX_YCOORDINATE_LEN / 8]byte
	Hash        [32]byte // 明文的杂凑值
	CipherLen   uint32   // 密文数据长度
	Cipher      []byte   // 密文数据
}

ECCCipherBlob ECC密文数据结构

type ECCPrivateKeyBlob 

type ECCPrivateKeyBlob struct {
	BitLen     uint32                             // 模数的实际位长度，8的倍数
	PrivateKey [ECC_MAX_MODULUS_BITS_LEN / 8]byte // 私有密钥
}

ECCPrivateKeyBlob ECC私钥数据结构

type ECCPublicKeyBlob 

type ECCPublicKeyBlob struct {
	BitLen      uint32                            // 模数实际位长，8的倍数
	XCoordinate [ECC_MAX_XCOORDINATE_LEN / 8]byte // 曲线上点的X坐标
	YCoordinate [ECC_MAX_YCOORDINATE_LEN / 8]byte // 曲线上点的Y坐标
}

ECCPublicKeyBlob ECC公钥数据结构

func GenECCKeyPair added in v0.0.6 

func GenECCKeyPair(cHandle unsafe.Pointer) (*ECCPublicKeyBlob, error)

GenECCKeyPair 生成ECC签名密钥对

cHandle 容器句柄 algId 算法标识

type ECCSignatureBlob 

type ECCSignatureBlob struct {
	// contains filtered or unexported fields
}

ECCSignatureBlob ECC签名数据结构

type EnvelopedKeyBlob 

type EnvelopedKeyBlob struct {
	Version uint32 // 版本号

	PubKey        ECCPublicKeyBlob // 加密密钥对的公钥
	ECCCipherBlob ECCCipherBlob    // 用保护公钥加密过的对称密钥密文
	// contains filtered or unexported fields
}

EnvelopedKeyBlob ECC加密密钥对保护结构

type FileAttribute 

type FileAttribute struct {
	FilName     [32]byte // 文件名，以‘\0’结束的ASCII字符串
	FileSize    uint32   // 文件大小
	ReadTights  uint32   // 读权限
	WriteRights uint32   // 写权限
}

FileAttribute 文件属性

func GetFileInfo 

func GetFileInfo(handle unsafe.Pointer, filename string) (*FileAttribute, error)

GetFileInfo 获取名称为 filename 的文件信息

handle 应用句柄 filename 文件名称

type FileInfo 

type FileInfo struct {
	Filename    string // 文件名称
	Size        uint32 // 文件大小
	ReadRights  uint32 // 文件读权限
	WriteRights uint32 // 文件写权限
}

type PINInfo 

type PINInfo struct {
	MaxRetryCount    uint32 // 最大重试次数
	RemainRetryCount uint32 // 当前剩余重试次数
	IsDefaultPin     bool   // 是否是出厂默认PIN
}

type RSAPrivateKeyBlob 

type RSAPrivateKeyBlob struct {
	AlgID           uint32                        // 算法标识号
	BitLen          uint32                        // 模数的实际位长度，8的倍数
	Modulus         [MAX_RSA_MODULUS_LEN]byte     // 模数，实际长度为BitLen/8字节
	PublicExponent  [MAX_RSA_EXPONENT_LEN]byte    // 公开密钥，一般为00010001
	PrivateExponent [MAX_RSA_MODULUS_LEN]byte     // 私有密钥，实际长度为BitLen/8字节
	Prime1          [MAX_RSA_MODULUS_LEN / 2]byte // 素数p，实际长度为BitLen/16字节
	Prime2          [MAX_RSA_MODULUS_LEN / 2]byte // 素数q，实际长度为BitLen/16字节
	Prime1Exponent  [MAX_RSA_MODULUS_LEN / 2]byte // d mod（p-1）的值，实际长度为BitLen/16字节
	Prime2Exponent  [MAX_RSA_MODULUS_LEN / 2]byte // d mod（q-1）的值，实际长度为BitLen/16字节
	Coefficient     [MAX_RSA_MODULUS_LEN / 2]byte // q 模 p的乘法逆元，实际长度为BitLen/16字节
}

RSAPrivateKeyBlob RSA私钥数据结构

type RSAPublicKeyBlob 

type RSAPublicKeyBlob struct {
	AlgID          uint32                     // 算法标识号
	BitLen         uint32                     // 模数的实际位长度，8的倍数
	Modulus        [MAX_RSA_MODULUS_LEN]byte  // 模数，实际长度为BitLen/8字节
	PublicExponent [MAX_RSA_EXPONENT_LEN]byte // 公开密钥，一般为00010001
}

RSAPublicKeyBlob RSA公钥数据结构

type Version 

type Version struct {
	Major byte // 主版本号
	Minor byte // 次版本号
}

Version 版本

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.