使用持有者應用程式處理憑證核發作業

如要接收及儲存核發機構提供的憑證，持卡人應用程式必須處理核發流程。憑證核發作業可透過下列兩種方式觸發：

  • 發卡機構啟動流程：使用者透過發卡機構應用程式或網站，觸發核發 VDC 的要求。舉例來說，網站可能會提供「將護照新增至錢包」選項。核發者會呼叫 Credential Manager 核發 API，提出 OpenID4VCI 憑證提供要求。如要處理這類要求，持有者必須先與 Credential Manager 整合，註冊其中繼資料。Credential Manager 會顯示相關選項供使用者選取。使用者選取持有者選項後，系統會叫用持有者應用程式，並繼續執行完成核發所需的步驟。
  • 持有人啟動流程：使用者要求從持有人應用程式新增 VDC。舉例來說，持有人可能會提供「新增護照」按鈕。 在這種情況下，持卡人會維護支援的發卡機構清單和中繼資料。不必與 Android Credential Manager 整合，即可完成這項功能。

如要進一步瞭解憑證如何與 Holder API 搭配運作，請參閱「關於儲存數位憑證」。

Android 版本相容性

Holder API 支援 Android 6 (API 級別 23) 以上版本。

導入作業

如要使用 Credential Manager Holder API，請將下列依附元件新增至應用程式模組的建構指令碼：

Groovy

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

Kotlin

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

建立 RegistryManager

建立 RegistryManager 執行個體，並向其註冊 RegisterCreationOptionsRequest 要求。

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

比對器是 WebAssembly (Wasm) 二進位檔案，會接收註冊期間設定的 creationOptions，以及核發者傳送的憑證，藉此判斷 Credential Manager UI 顯示的項目。如需比對器範例，請參閱開放原始碼範例錢包應用程式。

處理核發要求

接下來，錢包需要處理使用者選取憑證建立選項的情況。定義一個活動，用於監聽 androidx.credentials.registry.provider.action.CREATE_CREDENTIAL 意圖篩選器，如錢包範例所示。

啟動活動的意圖包含建立要求和呼叫來源，您可以使用 PendingIntentHandler.retrieveProviderCreateCredentialRequest 函式擷取這些資訊。API 會傳回 ProviderCreateCredentialRequest，其中包含與建立要求相關的所有資訊。主要有兩個部分：

  • 提出要求的應用程式。您可以使用 getCallingAppInfo 擷取這個字串。
  • 通話應用程式發出的要求。您可以使用 getCallingRequest 擷取這項資訊，系統會傳回 CreateCredentialRequest。如果要求是數位憑證，則為 CreateDigitalCredentialRequest 的例項，其中包含 requestJson 屬性中的核發要求 JSON。您可以使用下列程式碼範例處理：
val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

金鑰認證

請注意下列金鑰認證事項：

  • 產生金鑰認證時，您可能會使用 BigInteger.toByteArray 將金鑰內容轉換為 JSON Web 金鑰等。這種方法有時會加入正負號位元組，導致驗證錯誤。如果發生這種情況，請先移除這些位元組，再將金鑰認證傳送給發卡機構。
  • 建議使用 android_key_attestation 做為金鑰證明類型。

傳回建立回應

錢包完成儲存憑證所需的步驟後，請使用憑證回應完成活動：

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

如有例外狀況，您也可以傳送憑證例外狀況：

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

如要查看在情境中傳回憑證回應的完整範例，請參閱範例應用程式。