skf_api/native/
access.rs

1//! 访问控制接口
2//! - SKF_ChangeDevAuthKey
3//! - SKF_DevAuth
4//! - SKF_ChangePIN
5//! - SKF_GetPINInfo
6//! - SKF_VerifyPIN
7//! - SKF_UnblockPIN
8//! - SKF_ClearSecureState
9//!
10//! see [GM/T 0016-2012](https://github.com/guanzhi/GM-Standards/blob/master/GMT%E5%AF%86%E7%A0%81%E8%A1%8C%E6%A0%87/GMT%200017-2012%20%E6%99%BA%E8%83%BD%E5%AF%86%E7%A0%81%E9%92%A5%E5%8C%99%E5%AF%86%E7%A0%81%E5%BA%94%E7%94%A8%E6%8E%A5%E5%8F%A3%E6%95%B0%E6%8D%AE%E6%A0%BC%E5%BC%8F%E8%A7%84%E8%8C%83.PDF)
11//!
12//! ## 权限分类
13//! 权限分为设备权限，用户权限和管理员权限。
14//! - 设备权限：通过设备认证后获得设备权限。
15//! - 用户权限：用户PIN码验证通过后，获得用户权限，用户权限只作用于其所在的应用。
16//! - 管理员权限：管理员PIN码验证通过后，获得管理员权限，管理员权限只作用于其所在的应用。
17//!
18//! ## 设备认证
19//!  必须通过设备认证后才能在设备内创建和删除应用。设备认证使用分组密码算法和设备认证密钥进行。认证的流程如下：
20//!  1. 被认证方调用SKF_GetRandom 函数从设备获取8字节随机数 RND，并用`0x00`将其填充至密码算法的分块长度，组成数据块 `D0`
21//!  2. 被认证方对`D0`加密，得到加密结果`D1`，并调用`SKF_DevAuth`，将`D1`发送至设备；
22//!  3. 设备收到`D1`后，验证`D1`是否正确。正确则通过设备认证，否则设备认证失败。
23
24use crate::native::types::{BOOL, BYTE, HANDLE, LPSTR, ULONG};
25
26#[allow(non_camel_case_types)]
27extern "C" {
28
29    /// 更改设备认证密钥
30    ///
31    /// [device_handle] `[IN]`连接时返回的设备句柄
32    ///
33    /// [key_value] `[IN]`密钥值
34    ///
35    /// [key_len] `[IN]`密钥长度
36    /// ## 权限要求
37    /// 设备认证成功后才能使用。
38    pub fn SKF_ChangeDevAuthKey(
39        device_handle: HANDLE,
40        key_value: *const BYTE,
41        key_len: ULONG,
42    ) -> ULONG;
43
44    /// 设备认证
45    ///
46    /// [device_handle] `[IN]`连接时返回的设备句柄
47    ///
48    /// [auth_data] `[IN]`认证数据
49    ///
50    /// [len] `[IN]`认证数据的长度
51    pub fn SKF_DevAuth(device_handle: HANDLE, auth_data: *const BYTE, len: ULONG) -> ULONG;
52
53    /// 修改PIN.可以修改Admin和User的PIN，如果原PIN错误，返回剩余重试次数，当剩余次数为0时，表示PIN已经被锁死
54    ///
55    /// [app_handle] `[IN]`应用句柄
56    ///
57    /// [pin_type] `[IN]`PIN类型，ADMIN_TYPE=0,USER_TYPE=1
58    ///
59    /// [sz_old_pin] `[IN]`原PIN值
60    ///
61    /// [sz_new_pin] `[IN]`新PIN值
62    ///
63    /// [retry_count] `[OUT]`出错后重试次数
64    pub fn SKF_ChangePIN(
65        app_handle: HANDLE,
66        pin_type: ULONG,
67        sz_old_pin: LPSTR,
68        sz_new_pin: LPSTR,
69        retry_count: *mut ULONG,
70    ) -> ULONG;
71
72    /// 获取PIN码信息，包括最大重试次数、当前剩余重试次数，以及当前PIN码是否为出厂默认PIN码
73    ///
74    /// [app_handle] `[IN]`应用句柄
75    ///
76    /// [pin_type] `[IN]`PIN类型
77    ///
78    /// [max_retry_count] `[OUT]`最大重试次数
79    ///
80    /// [remain_retry_count] `[OUT]`当前剩余重试次数，当为0时表示已锁死
81    ///
82    /// [default_pin] `[OUT]`是否为出厂默认PIN码
83    pub fn SKF_GetPINInfo(
84        app_handle: HANDLE,
85        pin_type: ULONG,
86        max_retry_count: *mut ULONG,
87        remain_retry_count: *mut ULONG,
88        default_pin: *mut BOOL,
89    ) -> ULONG;
90
91    /// 校验PIN码。校验成功后，会获得相应的权限，如果PIN码错误，会返回PIN码的重试次数，当重试次数为0时表示PIN码已经锁死
92    ///
93    /// [app_handle] `[IN]`应用句柄
94    ///
95    /// [pin_type] `[IN]`PIN类型，ADMIN_TYPE=0,USER_TYPE=1
96    ///
97    /// [sz_pin] `[IN]`PIN值
98    ///
99    /// [retry_count] `[OUT]`出错后返回的重试次数
100    pub fn SKF_VerifyPIN(
101        app_handle: HANDLE,
102        pin_type: ULONG,
103        sz_pin: LPSTR,
104        retry_count: *mut ULONG,
105    ) -> ULONG;
106
107    /// 解锁用户PIN码.当用户的PIN码锁死后，通过调用该函数来解锁用户PIN码。解锁后，用户PIN码被设置成新值，用户PIN码的重试次数也恢复到原值。
108    ///
109    /// 验证完管理员 PIN才能够解锁用户  PIN 码，如果输入的 管理员 PIN 不正确或者已经锁死，会调用失败，并返回 管理员 PIN 的重试次数。
110    ///
111    /// [app_handle] `[IN]`应用句柄
112    ///
113    /// [sz_admin_pin] `[IN]`管理员PIN码
114    ///
115    /// [sz_new_user_pin] `[IN]`新的用户PIN码
116    ///
117    /// [retry_count] `[OUT]`管理员PIN码错误时，返回剩余重试次数
118    ///
119    pub fn SKF_UnblockPIN(
120        app_handle: HANDLE,
121        sz_admin_pin: LPSTR,
122        sz_new_user_pin: LPSTR,
123        retry_count: *mut ULONG,
124    ) -> ULONG;
125
126    /// 清除应用当前的安全状态
127    ///
128    /// [app_handle] `[IN]`应用句柄
129    pub fn SKF_ClearSecureState(app_handle: HANDLE) -> ULONG;
130}
skf_api/native/access.rs

skf_api/native/
access.rs
