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

如要接收及儲存核發機構的憑證，持有人應用程式必須處理核發流程。在核發流程中，核發者網站或應用程式會將憑證提供給持有者應用程式，詳細說明佈建憑證所需的資訊。持有人應用程式會使用 RegistryManager 向 Credential Manager 註冊要處理的憑證類型。這樣一來，使用者在提出憑證核發要求時，就能看到並選取該應用程式。

如要進一步瞭解憑證如何搭配 Holder API 運作，請參閱「Holder API 核心概念」。

Android 版本相容性

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

實作

如要使用 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 網頁金鑰等格式。這個方法有時會新增符號位元組，導致驗證錯誤。 如果發生這種情況，請先移除這些位元組，再將金鑰認證傳送給簽發者。
  • 建議使用 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()

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