Dijital Kimlik Bilgilerinin Yüz Yüze Kabul Edilmesi (Çevrimdışı)

Bu kılavuzda, güvenen tarafların (RP'ler) ve okuyucu geliştiricilerin, Google Cüzdan'dan sunulan dijital kimlik bilgilerinin yüz yüze (çevrimdışı) doğrulamasını uluslararası ISO/IEC 18013-5 standardına göre nasıl uygulayabileceği açıklanmaktadır.

Google Cüzdan'daki dijital kimlikler, sunum sırasında etkin bir internet bağlantısı gerektirmeden fiziksel ortamlarda (ör. satış noktası terminalleri, etkinlik mekanları, toplu taşıma kapıları, kolluk kuvvetleri okuyucuları ve mobil okuyucu uygulamaları) güvenli bir şekilde doğrulanabilir.

Çevrimdışı Sunum'a (ISO/IEC 18013-5) genel bakış

ISO/IEC 18013-5 standardı, Sahip (Google Cüzdan'ın çalıştığı kullanıcının mobil cihazı) ile Okuyucu / Doğrulayıcı (fiziksel bir terminal veya tamamlayıcı mobil uygulama) arasında çevrimdışı sunum için standartlaştırılmış, birlikte çalışabilir bir protokol tanımlar.

Sunu akışı farklı aşamalarda gerçekleşir:

  1. Cihaz etkileşimi: Okuyucu ve cüzdan, NFC teması (statik veya anlaşmalı aktarım) ya da QR kodu taraması aracılığıyla ilk teması kurar. Bu aşamada cihaz etkileşimi meta verileri ve okuyucunun kısa ömürlü ortak anahtarı (EReaderKey) paylaşılır.
  2. Veri Taşıma Bağlantısı: Güvenli ve şifrelenmiş bir Bluetooth Düşük Enerji (BLE) kanalı üzerinde anlaşılır (okuyucu, Merkezi İstemci veya Çevresel Sunucu modunda çalışır).
  3. Cihaz İsteği: Okuyucu, istenen belge türünü (ör. org.iso.18013.5.1.mDL) ve istenen ad alanlarını ve veri öğelerini belirten, CBOR kodlu bir DeviceRequest iletir.
  4. Kullanıcı Rızası ve Cihaz Kimlik Doğrulaması: Google Cüzdan, kullanıcıdan istenen veri öğelerini incelemesini ve biyometrik kimlik doğrulama veya ekran kilidi kullanarak paylaşımı onaylamasını ister.
  5. Cihaz Yanıtı ve Şifreleme Doğrulaması: Cüzdan, imzalı Mobil Güvenlik Nesnesi'ni (MSO) ve cihaz tarafından imzalanmış veri öğelerini içeren CBOR kodlu bir DeviceResponse geri gönderir. Okuyucu, kriptografik imzaları güvenilir kök sertifikalara göre doğrular.

Multipaz Açık Kaynak SDK'sı

Okuyucu veya doğrulayıcı uygulaması uygulamak için Google, başlangıçta Google tarafından geliştirilen ve OpenWallet Foundation (OWF)'a katkıda bulunulan açık kaynaklı bir Kotlin Multiplatform (KMP) SDK'sı olan Multipaz'ın kullanılmasını önerir.

Multipaz; ISO/IEC 18013-5 okuyucu ve cüzdan protokolleri, kriptografik doğrulama işlem hatları, CBOR kodlama/kod çözme ve genişletilebilir belge türü şemaları için üretime hazır bir uygulama sağlar.

Multipaz'ı okuyucu uygulamanıza entegre etme

Aşağıdaki adımlarda, Multipaz SDK'sının Android okuyucu uygulamasına nasıl entegre edileceği gösterilmektedir.

1. adım: Bağımlılıkları ekleyin

Multipaz kitaplıkları Maven Central'da yayınlanır. Gerekli modülleri uygulamanızın build.gradle.kts dosyasına ekleyin:

// build.gradle.kts
dependencies {
    // Core Multipaz library (protocol engine, CBOR, crypto)
    implementation("org.multipaz:multipaz:0.100.0")

    // Android-specific platform bindings (NFC, BLE, Keystore)
    implementation("org.multipaz:multipaz-android:0.100.0")

    // Standardized document types (mDL, EU PID, etc.)
    implementation("org.multipaz:multipaz-doctypes:0.100.0")
}

2. adım: Android izinlerini yapılandırın

Yüz yüze doğrulama için NFC etkileşimi, kamera tarama (QR etkileşimi için) ve Bluetooth Düşük Enerji veri aktarımı için donanım izinleri gerekir. AndroidManifest.xml uygulamanıza aşağıdaki izinleri ekleyin:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- NFC Engagement -->
    <uses-permission android:name="android.permission.NFC" />
    <uses-feature android:name="android.hardware.nfc" android:required="false" />

    <!-- Camera for QR Code Engagement -->
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" android:required="false" />

    <!-- Bluetooth Low Energy Transport (Android 12+) -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
                     android:usesPermissionFlags="neverForLocation" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

    <!-- Legacy Bluetooth Permissions for Android 11 and lower -->
    <uses-permission android:name="android.permission.BLUETOOTH"
                     android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
                     android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                     android:maxSdkVersion="30" />
</manifest>

3. adım: Doğrulama motorunu başlatın

Etkileşim etkinliklerini işlemek ve BLE iletişimi yaşam döngüsünü yönetmek için Multipaz'ın VerificationHelper veya Reader bağlantı soyutlamalarını kullanın:

import org.multipaz.verification.VerificationHelper
import org.multipaz.cbor.Cbor
import org.multipaz.crypto.Crypto

class ReaderManager(private val context: android.content.Context) {

    private var verificationHelper: VerificationHelper? = null

    fun startListeningForEngagement() {
        verificationHelper = VerificationHelper.Builder(
            context = context,
            listener = object : VerificationHelper.Listener {
                override fun onDeviceConnected() {
                    // BLE channel established, send request
                    sendDeviceRequest()
                }

                override fun onResponseReceived(deviceResponseBytes: ByteArray) {
                    // Process and verify the received credential payload
                    handleDeviceResponse(deviceResponseBytes)
                }

                override fun onError(error: Throwable) {
                    // Handle transport or protocol errors
                }

                override fun onDeviceDisconnected(transportTransportSpecificTermination: Boolean) {
                    // Connection closed
                }
            }
        ).build()
    }
}

4. adım: DeviceRequest'i oluşturun

Uygulamanızın doğrulamasını yapması gereken belge türünü ve bireysel veri öğelerini belirtin. Her zaman en az bilgi paylaşımı ilkesini uygulayın (ör. yaş doğrulanırken tam birth_date yerine yalnızca age_over_21 istenmelidir):

fun sendDeviceRequest() {
    // Specify the DocType and requested elements
    val docType = "org.iso.18013.5.1.mDL"
    val namespace = "org.iso.18013.5.1"

    // Map of requested elements: elementName -> intentToRetain
    val requestedElements = mapOf(
        "family_name" to false,
        "given_name" to false,
        "age_over_21" to false,
        "portrait" to false,
        "driving_privileges" to false
    )

    // Build ISO/IEC 18013-5 DeviceRequest structure
    val deviceRequestBytes = verificationHelper?.buildDeviceRequest(
        docType = docType,
        itemsToRequest = mapOf(namespace to requestedElements)
    )

    if (deviceRequestBytes != null) {
        verificationHelper?.sendDeviceRequest(deviceRequestBytes)
    }
}

Ek belge türlerini (DocTypes) destekleme

Multipaz, standartlaştırılmış kimlik bilgilerini kutudan çıkar çıkmaz destekler ve özel veya alana özgü belge türleri istemek için genişletilebilir bir mimari sunar.

1. Yerleşik Standart Belge Türleri

multipaz-doctypes kitaplığı, standart kimlik bilgileri için önceden tanımlanmış şema modelleri sağlar:

Belge Türü Tanımlayıcısı Standart / Kapsam Tipik Ad Alanı Ortak Öğeler
org.iso.18013.5.1.mDL ISO/IEC 18013-5 Mobil Sürücü Belgesi org.iso.18013.5.1 family_name, given_name, birth_date, issue_date, expiry_date, issuing_authority, document_number, portrait, driving_privileges, age_over_18, age_over_21
eu.europa.ec.eudi.pid.1 AB Dijital Kimlik Cüzdanı (EUDIW) Kişi Tanımlama Verileri eu.europa.ec.eudi.pid.1 family_name, first_name, birth_date, nationality, issuing_country, issuing_authority, personal_administrative_number
com.google.wallet.idcard.1 Google Cüzdan kimlik kartı / test kimlikleri com.google.wallet.idcard.1 given_name, family_name, birth_date, document_number, portrait

2. Özel Belge Türleri İsteğinde Bulunma

Özel belge türleri istemek için DeviceRequest oluştururken hedef docType dizesini ve ilgili ad alanı eşlemelerini tanımlayın:

// Example: Requesting a custom event ticket credential
val customDocType = "com.example.events.ticket"
val customNamespace = "com.example.events.ticket.1"

val customRequestedItems = mapOf(
    "ticket_id" to false,
    "event_name" to false,
    "seat_section" to false,
    "vip_access" to false
)

val multiDocRequestBytes = verificationHelper?.buildMultiDocDeviceRequest(
    documents = listOf(
        DocumentRequest(
            docType = customDocType,
            namespaces = mapOf(customNamespace to customRequestedItems)
        )
    )
)

Kriptografik Doğrulama ve Güven Yönetimi

Yanıt yükü almak yalnızca ilk adımdır. Okuyucular, sunulan kimlik bilgisinin gerçekliğini ve bütünlüğünü doğrulamak için dört adımlı bir şifreleme doğrulaması yapmalıdır.

Doğrulama Adımı Doğrulama Hedefi
1. Kart Sağlayıcı Kimlik Doğrulaması IssuerAuth (COSE_Sign1) öğesini güvenilir IACA kök sertifikalarına göre doğrulayın
2. Geçerlilik dönemi kontrolü validFrom ≤ şu anki saat ≤ validUntil olduğundan emin olun.
3. Veri Bütünlüğü Kontrolü Döndürülen öğelerin SHA-256 özetlerini hesaplayın ve MSO ile eşleştirin. ValueDigests
4. Cihaz Doğrulaması SessionTranscript'ye bağlı DeviceKey kullanarak DeviceSigned imzasını veya MAC'i doğrulayın.

1. 4 Adımlı Doğrulama Ardışık Düzeni

  1. Kart Sağlayıcı Kimlik Doğrulaması (IssuerAuth):
    • Mobil Güvenlik Nesnesi (MSO), Düzenleyen Yetkili (IssuerAuth yükü) tarafından imzalanır.
    • Okuyucu, COSE_Sign1 imzasını Belge İmzalayan sertifikasını kullanarak doğrular ve sertifikanın güvenilir bir Düzenleyici Yetkili CA (IACA) kök sertifikasına kadar zincirlendiğinden emin olur.
  2. Geçerlilik aralığı doğrulaması:
    • Okuyucu, kimlik bilgisinin süresinin dolmadığından emin olmak için MSO'daki validityInfo.validFrom ve validityInfo.validUntil zaman damgalarını okuyucunun mevcut saatiyle karşılaştırır.
  3. Veri Bütünlüğü Doğrulaması (ValueDigests):
    • Okuyucu, alınan her IssuerSignedItem için özetini (ör. SHA-256) hesaplar ve MSO'nun ValueDigests sözlüğündeki karşılık gelen karma girişiyle eşleştiğini doğrular.
  4. Cihaz kimlik doğrulaması (DeviceSigned):
    • Okuyucu, kimlik bilgisini sunan cihazın, imzalı MSO'da yayınlanan DeviceKey karşılık gelen özel anahtarı tuttuğunu doğrular.
    • Bu işlem, DeviceAuth (DeviceSignature veya DeviceMac) öğesinin SessionTranscript üzerinden doğrulanması, oturumun okuyucunun kısa ömürlü anahtarına bağlanması ve yeniden oynatma ile ortadaki adam saldırılarının önlenmesiyle gerçekleştirilir.

2. Güvenilir IACA kök sertifikalarını yönetme

Üretim okuyucuları, güvenilir IACA kök sertifikalarını içeren güvenli bir yerel güvenilir sertifika deposu bulundurmalıdır:

  • Üretim IACA Sertifikaları: Kök sertifikaları resmi veren yetkililerden indirip yapılandırın. Desteklenen Düzenleyen Kuruluşlar ve IACA Sertifikaları listemize bakın.
  • AAMVA VICAL: ABD yargı alanlarında, okuyucu sistemleri eyalet güven köklerini otomatik olarak senkronize etmek için American Association of Motor Vehicle Administrators (AAMVA) Verified Issuer Certificate Authority List (VICAL) hizmetiyle entegre edilebilir.
  • Korumalı alan testinin kökleri: Korumalı alan kimlik bilgilerine karşı test yaparken okuyucunun Google Sandbox IACA Root'a güvendiğinden emin olun.
import org.multipaz.crypto.X509Cert

// Configure trusted IACA certificates in the trust store
val trustedCertificates = mutableListOf<X509Cert>()

// Add official state IACA certificates
trustedCertificates.add(X509Cert.fromPem(sampleStateIacaPem))

// Add Google Sandbox IACA root certificate for testing
trustedCertificates.add(X509Cert.fromPem(googleSandboxIacaPem))

val verifier = MultipazVerifier(trustStore = trustedCertificates)
val verificationResult = verifier.verify(deviceResponseBytes, sessionTranscript)

if (verificationResult.isIssuerAuthorized && verificationResult.isDeviceAuthenticated) {
    // Credential is valid and authentic
} else {
    // Reject presentation: cryptographic validation failed
}

Okuyucu Kimlik Doğrulaması (Önerilir)

Okuyucu Kimlik Doğrulaması, yetkili bir X.509 okuyucu sertifikası kullanarak ReaderAuthentication yapısını imzalayarak okuyucu uygulamasının kimliğini Google Cüzdan'da kriptografik olarak kanıtlamasına olanak tanır.

  • Neden Önerilir? Okuyucu kimlik doğrulaması, okuyucu uygulamanızın veya terminalinizin kullanıcıya güvenilir bir kimlik sunmasına olanak tanır. Temel herkese açık özellikler (ör.age_over_21 doğrulama) için isteğe bağlı olsa da kullanıcı güvenini artırmak amacıyla okuyucu entegrasyonları için önemle tavsiye edilir ve hassas özellikler (ör. tam sosyal güvenlik numarası, ikamet adresi veya belirli eyalet onayları) istenirken yasal olarak ya da politika gereği zorunlu olabilir.
  • İşleyiş şekli: Okuyucu, sertifika zincirini içerir ve oturum transkriptini imzalar. Google Cüzdan, veri yayınlanmadan önce kullanıcı rızası ekranında okuyucunun doğrulanmış kimliğini ve kuruluş adını kullanıcıya gösterir.

Test ve Geliştirme Araçları

Entegrasyonu hızlandırmak için aşağıdaki geliştirici araçlarını ve referans uygulamalarını kullanın:

  1. Multipaz Referans Uygulamaları:
    • Multipaz deposunu klonlayın ve fiziksel doğrulama akışlarını test etmek için IdentityReader Android örnek uygulamasını çalıştırın.
  2. Google Cüzdan'da test kimliği oluşturma:
  3. Web Tabanlı Doğrulayıcı Testi:
    • CBOR isteklerini incelemek, hak talebi sorgularını keşfetmek ve W3C / ISO 18013-7 web tabanlı sunumlarını test etmek için verifier.multipaz.org adresini kullanın.

Sorun giderme ve saha teşhisi

Aşağıdaki tabloda, çevrimdışı doğrulama sırasında karşılaşılan yaygın sorunlar ve önerilen çözümler listelenmiştir:

Sorun / Belirti Temel Neden Önerilen Çözüm
BLE bağlantısı zaman aşımına uğruyor / Bağlantı başarısız oluyor
  • Yüksek yoğunluklu ortamlarda RF paraziti.
  • Belirli okuyucu donanımlarında çevre birimi ve merkezi mod uyumsuzluğu.
  • Tarama zaman aşımları.
  • Okuyucunun hem BLE Central Client hem de Peripheral Server modlarını desteklediğinden emin olun.
  • Etkin etkileşim sırasında agresif tarama için BLE tarama penceresini ve aralığını ayarlayın.
  • MTU boyutu pazarlığının başarıyla tamamlandığını doğrulayın.
NFC ile dokunma işlemi başarısız oluyor veya düşüyor Kullanıcı, BLE devretme kaydı tamamen aktarılmadan önce mobil cihazı okuyucu anteninden uzaklaştırır.
  • NFC etkileşimi başlar başlamaz terminalde anında görsel/işitsel/dokunsal geribildirim sağlayın.
  • Kullanıcılara, BDE bağlantısı kurulana kadar telefonu NFC hedefi üzerinde sabit tutmalarını söyleyin.
UNTRUSTED_ISSUER / Sertifika zinciri hatası Belge İmzalayan sertifikası, okuyucunun yerel güvenilir sertifika deposundaki güvenilir bir IACA sertifikasına zincirlenmiyor.
  • Verenin kök sertifikasının okuyucu güvenilir sertifika deposuna yüklendiğini kontrol edin.
  • Korumalı alanda test yapıyorsanız Google Sandbox IACA Root'un yüklendiğini doğrulayın.
  • IACA sertifika listelerinin (ör. AAMVA VICAL) düzenli olarak güncellendiğinden emin olun.
INVALID_VALIDITY_INFO / Süresi Dolmuş MSO
  • Okuyucunun sistem saati senkronize değil.
  • MSO imzasının süresi doldu.
  • Okuyucu cihazın, sistem saatini NTP üzerinden düzenli olarak senkronize ettiğinden emin olun.
  • Kullanıcıdan, kimlik bilgisi jetonlarını yenilemek için internete bağlıyken Google Cüzdan'ı açmasını isteyin.
DEVICE_AUTHENTICATION_FAILED Oturum transkripti ile okuyucu ve cüzdan arasında uyuşmazlık var veya geçici cihaz imzası geçersiz.
  • DeviceEngagementBytes ve EReaderKeyBytes öğelerinin tam ham baytlarının, yeniden kodlanmadan SessionTranscript yapısında korunmasını sağlayın.
Android 12 ve sonraki sürümlerde izin kilitlenmesi Uygulama, çalışma zamanı izinleri olmadan BLE üzerinden tarama veya reklam yayınlama girişiminde bulundu.
  • Okuyucu oturumlarını başlatmadan önce çalışma zamanında BLUETOOTH_SCAN, BLUETOOTH_CONNECT ve BLUETOOTH_ADVERTISE öğelerini kontrol edin ve isteyin.

Yüz yüze okuyucular için kullanıcı deneyimi ve gizlilik kuralları

Fiziksel okuyucuları ve yardımcı uygulamaları tasarlarken:

  • Kullanıcı arayüzünde seçici açıklama yapın: Operatöre yalnızca kararı veya gerekli minimum özelliği gösterin (ör. kullanıcının tam doğum tarihini, adresini ve sürücü belgesi numarasını göstermek yerine belirgin bir yeşil onay işareti ve "21 yaş ve üzeri doğrulandı" ifadesini gösterin).
  • Net Fiziksel Etkileşim Göstergeleri: NFC hedef bölgesini net bir şekilde etiketleyin ve her aşamayı gösteren görsel ipuçları (ör. animasyonlar veya ilerleme çubukları) gösterin: Dokunma / Tarama → Bağlanma → Doğrulama → Tamamlandı.
  • Geçici Veri İşleme: Cüzdandan alınan kişisel veri öğelerini, geçerli yasa açıkça gerektirmediği ve intentToRetain = true aracılığıyla açıklanmadığı sürece saklamayın veya günlüğe kaydetmeyin.