ניהול הנפקת פרטי הכניסה באמצעות אפליקציית המחזיק

כדי לקבל ולאחסן פרטי כניסה מגורמים מנפיקים, אפליקציית המחזיק צריכה לטפל בתהליכי הנפקה. בתהליך הנפקת תעודה, האתר או האפליקציה של הגורם המנפיק שולחים הצעה לתעודה לאפליקציה של המחזיק, עם פירוט המידע שנדרש להקצאת תעודה. אפליקציית המחזיק משתמשת ב-RegistryManager כדי לרשום ב-Credential Manager את סוגי פרטי הכניסה שהיא מתכוונת לטפל בהם. כך האפליקציה תוצג למשתמש והוא יוכל לבחור אותה במהלך בקשת הנפקה כדי לקבל את האישורים.

במאמר מושגי הליבה של Holder API מוסבר איך פרטי הכניסה פועלים עם Holder API.

תאימות לגרסת Android

‫Holder API נתמך ב-Android 6 (רמת API‏ 23) ומעלה.

הטמעה

כדי להשתמש ב-Credential Manager Holder API, מוסיפים את יחסי התלות הבאים לסקריפט ה-build של מודול האפליקציה:

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"

}

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. דוגמה להתאמה אפשר לראות באפליקציית הארנק בקוד פתוח.

טיפול בבקשה להנפקה

לאחר מכן, הארנק צריך לטפל במצב שבו המשתמש בוחר באפשרות ליצירת אמצעי תשלום. מגדירים פעילות שמקשיבה למסנן ה-Intent‏ androidx.credentials.registry.provider.action.CREATE_CREDENTIAL, כמו שמוצג בארנק לדוגמה.

ה-Intent שמפעיל את הפעילות מכיל את בקשת היצירה ואת מקור הקריאה, שאפשר לחלץ באמצעות הפונקציה PendingIntentHandler.retrieveProviderCreateCredentialRequest. ה-API מחזיר ProviderCreateCredentialRequest שמכיל את כל המידע שמשויך לבקשת היצירה. יש שני רכיבים מרכזיים:

• האפליקציה ששלחה את הבקשה. אפשר לאחזר את הנתונים באמצעות getCallingAppInfo.
• הבקשה מאפליקציית השיחות. אפשר לאחזר אותה באמצעות getCallingRequest, שמחזירה CreateCredentialRequest. אם הבקשה היא לקבלת פרטי כניסה דיגיטליים, היא מופע של CreateDigitalCredentialRequest, שמכיל את בקשת ההנפקה ב-JSON במאפיין requestJson. אפשר לעבד את הנתונים באמצעות הקוד לדוגמה הבא:

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()

כדי לראות דוגמה מלאה להחזרת תגובת האישורים בהקשר, אפשר לעיין באפליקציה לדוגמה.