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

כדי לקבל ולאחסן פרטי כניסה ממנפיקים, אפליקציית המחזיק צריכה לטפל בתהליכי ההנפקה. יש שתי דרכים להנפיק פרטי כניסה:

• תהליך שמופעל על ידי המנפיק: המשתמש מפעיל בקשה להנפקת VDC מאפליקציה או מאתר של מנפיק. לדוגמה, אתר מסוים יכול להציע למשתמשים את האפשרות "הוספת הדרכון לארנק". מנפיק האישורים קורא ל-API להנפקת אישורים של Credential Manager כדי לשלוח בקשה להצעת אישור OpenID4VCI. כדי לטפל בבקשות כאלה, בעל המסמך צריך קודם לשלב את Credential Manager כדי לרשום את המטא-נתונים שלו. ב-Credential Manager יוצגו אפשרויות רלוונטיות לבחירת המשתמש. אחרי שהמשתמש בוחר אפשרות של מחזיק, אפליקציית המחזיק תופעל ותוכל להמשיך בשלבים הנדרשים להשלמת ההנפקה.
• תהליך שמתחיל באפליקציה של בעל הכרטיס: המשתמש מבקש להוסיף VDC מהאפליקציה של בעל הכרטיס. לדוגמה, יכול להיות שיופיע כפתור "הוספת הדרכון". במקרה כזה, בעל התעודה מנהל את רשימת המנפיקים הנתמכים ואת המטא-נתונים. כדי להשלים את הפונקציה הזו, לא צריך לשלב את האפליקציה עם Credential Manager ב-Android.

מידע נוסף על אופן הפעולה של פרטי הכניסה עם 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. באפליקציית Wallet לדוגמה בקוד פתוח יש דוגמה למתאם.

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

בשלב הבא, הארנק צריך לטפל במצב שבו המשתמש בוחר באפשרות ליצירת פרטי כניסה. מגדירים פעילות שמאזינה למסנן ה-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()

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