ukey 功能適配文檔

本文檔主要介紹第三方設備廠商如何將 ukey 功能集成到系統中，另外也簡單描述了系統上的用戶認證流程。ukey 功能的集成需要實現系統定義的 ukey 接口規范，然后將實現的接口程序安裝到系統中，并提供規范中定義的配置文件，就可在重啟后使用系統的 ukey 功能了。

---

認證流程

系統上對用戶認證提供了一套統一的接口，這個認證接口負責啟用具體的認證方式，如啟用密碼認證、指紋認證等。認證的結果通過 DBus Signal 發出，DBus Signal 沒有具體的目標，可以認為是廣播的方式，即所有監聽了這個 Signal 的程序都會收到。在介紹適配步驟之前，先介紹下 ukey 的認證流程。

---

ukey功能適配

ukey 功能適配主要包括配置文件和ukey 接口規范兩部分

---

配置文件

---

配置文件適配步驟如下：

確定 ukey 接口的 DBus 服務名稱

DBus 服務的名稱包括以下內容：

• Service
  ukey 接口的 DBus Service Name ，在 DBus Bus 中應是唯一的。

• ObjectPath
  ukey 接口的 DBus Object ，指明服務所在的 path

• Interface
  ukey 接口的 DBus Interface ，指明服務所在的 interface ， interface 中應包括 ukey 接口規范中的所有接口。

提供接口配置文件
配置文件里需要描述接口的 DBus 信息，配置文件應安裝到 /usr/share/deepin-authentication/interfaces/ 目錄中。系統的認證接口在啟動時會掃描 /usr/share/deepin-authentication/interfaces/ 目錄，加載并檢查配置文件中定義的接口。

配置文件的格式如下：

{"service": "","path": "","interface": "","type": 2, }

各字段含義如下：

• Service
  DBus 接口的 service

• path
  DBus 接口的 object path

• interface
  DBus 接口的 interface

• type
  接口類型， 2 表示 ukey 接口

實現接口規范中的接口
ukey 接口規范中定義了適配時應該實現的接口，通過這些接口將 ukey 功能集成到系統中。ukey 接口規范后文中將會介紹。

提供DBus服務的配置文件
ukey 功能需要訪問硬件，所以一般是一個在 System Bus 上的服務。 System Bus 服務需要提供 .service 和 .conf 文件，說明如下：

• .service 文件
  .service 文件中會指明調用 service name 時應該執行的程序，格式如下：

  [D-BUS Service] Name=<service name> Exec=<app filepath> User=root

  字段描述如下：

  • Name

    DBus Service Name

  • Exec
    程序的執行路徑

  • User
    表明程序使用什么用戶啟動，一般為 root

  .service 應該安裝到 /usr/share/dbus-1/system-services/ 目錄中

• .conf文件
  .conf 文件中會規定接口的訪問權限，內容如下(以 com.deepin.Example 為 service name 和 interface name 為例)：

  <?xml version="1.0" encoding="UTF-8"?> <!-- -*- XML -*- --><!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> <busconfig><!-- Only root can own the service --><policy user="root"><allow own="com.deepin.Example"/></policy><!-- Allow anyone to invoke methods on the interfaces --><policy context="default"><allow send_destination="com.deepin.Example" /><allow send_destination="com.deepin.Example"send_interface="com.deepin.Example"/><allow send_destination="com.deepin.Example"send_interface="org.freedesktop.DBus.Properties"/><allow send_destination="com.deepin.Example"send_interface="org.freedesktop.DBus.Introspectable"/></policy></busconfig>

  .conf 文件安裝到 /usr/share/dbus-1/system.d/ 目錄中

---

ukey接口規范

下面將按照 Methods , Properties , Signals 一一介紹：

---

Methods

---

Verify(char* uuid,char* gid)

為指定 uuid 的用戶開啟 gid 次認證。如果設備沒有與該用戶綁定，則返回 dbus 錯誤信息，如果支持對該用戶的認證，則繼續進行認證操作。

• 參數：
  uuid：用戶的 uuid

  gid: 此次認證的 id

---

SetPin(char* uuid,char* gid,char* pin)

設置指定 uuid 的用戶的 gid 次認證的 pin 碼，設置完成后，驅動服務需要根據 pin 碼是否正確發送認證結果信號。

• 參數:
  uuid:用戶的 uuid

  gid: 此次認證的 id

  pin：pin 碼

---

StopVerify(char* uuid,char* gid)

結束 uuid 用戶的 gid 次認證，失敗則返回 dbus 錯誤信息，正常結束或中途取消都需要調用此方法。

• 參數:
  uuid:用戶的 uuid

  gid: 此次認證的 id

---

SetSessionPath(char* uuid,char* gid,char* path)

設置用戶當前 session 的 DBus 路徑，可以使用該 DBus 路徑對 uuid 用戶進行登出操作。此接口的調用根據配置文件。該接口可能不調用， path 可以被設置成空字符串。

• 參數：
  uuid：用戶的 uuid

  gid: 此次認證的 id

  path：當前 session 的 DBus 路徑

---

Properties

---

char *Name

（只讀）

設備名稱

---

int32 State

（只讀）

設備狀態，可以為以下位的組合：

enum {DeviceStateNormal = 1<<0, //設備正常可用DeviceStateVerifing = 1<<1, //設備正在驗證中 }

最低位表示設備是否正?？捎?#xff0c;沒設置表示設備不可用或有異常，設置了表示設備正?？捎?#xff1b;更高 1 位表示設備是否被正在驗證中，沒設置表示沒有被使用，即是空閑中，設置了表示正在驗證中。

---

int32 Type

（只讀）

設備類型，可以為以下值：

enum {DeviceTypeNormal = 0, //設備插入并驗證成功即可操作機器DeviceTypeDongle , //設備需要一直插入才可操作機器 }

DeviceTypeNormal 表示設備為正常 ukey 設備，插入并驗證成功之后即可獲得操作機器權限， ukey 可以拔出。
DeviceTypeDongle 表示設備為加密狗類型 ukey 設備，插入并驗證成功之后即可獲得操作機器權限，且 ukey 不能拔出，拔出之后可觸發鎖屏。（該操作由驅動服務調用）。

---

int32 Capability

（只讀）

設備是否支持同時開啟多次認證，可以為以下值：

enum {DeviceCapabilitySingle = 0, //只能同時開啟一次認證DeviceCapabilityMulti, //可以支持同時開啟多次認證 }

DeviceCapabilitySingle 表示 UKey 只能同時開啟一次認證，在上一次認證沒有結束時開啟下一次認證，會終止上一次認證。
DeviceCapabilityMulti 表示 UKey 可以支持同時開啟多次認證，在上一次認證沒有結束時開啟下一次認證，兩次認證可以同時進行。

---

Signals

---

VerifyResult(char* id,char* msg)

驗證結果。

• 參數

  id：用戶的 uuid

  msg： json 格式的認證結果，若成功，則 result 字段為1, description 字段可為空，若失敗，則 result 字段為0, descriprion 可給出對應的失敗描述信息。
  json 定義如下

  {"result":1,"description":"","id":"" }

  各字段功能描述：

  result：int 類型，認證結果。 0 為失敗， 1 為成功

  description： char* 類型，對認證結果的描述信息

  id: char* 類型，此次認證的 gid

---

總結

以上是生活随笔為你收集整理的ukey功能适配文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。