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

Bu kılavuzda, Güvenen Taraflar (RP'ler) ve okuyucu geliştiricilerin, Google Cüzdan'da 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 kimlik bilgileri, 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 kuvveti okuyucuları ve mobil okuyucu uygulamaları) güvenli bir şekilde doğrulanabilir.

Çevrimdışı Sunuma Genel Bakış (ISO/IEC 18013-5)

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

Sunum akışı farklı aşamalardan oluşur:

  1. Cihaz etkileşimi: Okuyucu ve cüzdan, NFC dokunma (statik veya anlaşmalı aktarım) ya da QR kodu tarama aracılığıyla ilk bağlantıyı kurar. Bu aşamada, cihaz etkileşimi meta verileri ve okuyucunun geçici ortak anahtarı (EReaderKey) değiş tokuş edilir.
  2. Veri Aktarım Bağlantısı: Güvenli, şifrelenmiş bir Bluetooth Düşük Enerji (BLE) kanalı üzerinde anlaşmaya varılır (okuyucu, Merkezi İstemci veya Çevre Birimi Sunucusu modunda çalışır).
  3. Cihaz İsteği: Okuyucu, istenen belge türünü (ör. org.iso.18013.5.1.mDL) ve istenen belirli ad alanları ile veri öğelerini belirten CBOR ile kodlanmış 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 Kriptografik Doğrulama: Cüzdan, imzalı Mobil Güvenlik Nesnesi (MSO) ve cihaz tarafından imzalanmış veri öğelerini içeren CBOR ile kodlanmış bir DeviceResponse gönderir. Okuyucu, kriptografik imzaları güvenilir kök sertifikalara göre doğrular.

Multipaz Açık Kaynak SDK'sı

Google, okuyucu veya doğrulayıcı uygulaması oluşturmak için Multipaz'ı kullanmanızı önerir. Multipaz, ilk olarak Google tarafından geliştirilen ve OpenWallet Foundation'a (OWF) katkıda bulunulan açık kaynaklı bir Kotlin Multiplatform (KMP) SDK'sıdır.

Multipaz; ISO/IEC 18013-5 okuyucu ve cüzdan protokollerinin, kriptografik doğrulama ardışık düzenlerinin, CBOR kodlama/kod çözme işlemlerinin ve genişletilebilir belge türü şemalarının üretime hazır bir uygulamasını sunar.

Multipaz'ı Okuyucu Uygulamanıza Entegre Etme

Aşağıdaki adımlarda, Multipaz SDK'sının bir 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. Uygulamanızın build.gradle.kts dosyasına gerekli modülleri 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 taraması (QR etkileşimi için) ve Bluetooth Düşük Enerji veri aktarımı için donanım izinleri gerekir. AndroidManifest.xml dosyanı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şim yaşam döngüsünü yönetmek için Multipaz'ın VerificationHelper veya okuyucu bağlantısı 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ı gereken belge türünü ve bireysel veri öğelerini belirtin. Her zaman minimum düzeyde açıklama ilkesini uygulayın (ör. yaş doğrulaması yaparken tam birth_date yerine yalnızca age_over_21 isteyin):

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

Multipaz, standartlaştırılmış kimlik bilgilerini kullanıma hazır olarak destekler ve özel veya alana özgü belge türlerini 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 Normal 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 Kimlik 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 dijital kimliği / Test Kimlikleri com.google.wallet.idcard.1 given_name, family_name, birth_date, document_number, portrait

2. Özel Belge Türleri İsteme

Özel doküman 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ın, sunulan kimlik bilgisinin gerçekliğini ve bütünlüğünü doğrulamak için dört adımlı bir kriptografik doğrulama gerçekleştirmesi gerekir.

Doğrulama Adımı Doğrulama Hedefi
1. Kartı Veren Kuruluşun Kimlik Doğrulaması IssuerAuth (COSE_Sign1) sertifikasını güvenilir IACA kök sertifikalarıyla doğrulayın
2. Geçerlilik Süresi Kontrolü validFrom ≤ geçerli saat ≤ validUntil olduğundan emin olun.
3. Veri Bütünlüğü Kontrolü Döndürülen öğelerin SHA-256 özetlerini hesaplayın ve MSO ValueDigests ile eşleştirin
4. Cihaz Kimlik Doğrulaması SessionTranscript ile ilişkili DeviceKey anahtarını kullanarak DeviceSigned imzasını veya MAC'ini doğrulama

1. 4 Adımlı Doğrulama Süreci

  1. Veren Kuruluş Kimlik Doğrulaması (IssuerAuth):
    • Mobil Güvenlik Nesnesi (MSO), Veren Yetkili tarafından imzalanır (IssuerAuth yükü).
    • Okuyucu, Doküman İmzalayan sertifikasını kullanarak COSE_Sign1 imzasını doğrular ve sertifikanın güvenilir bir Sertifika Veren Yetkili CA (IACA) kök sertifikasına bağlı olduğundan 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 geçerli saatine göre kontrol eder.
  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 ilgili karma girişle eşleştiğini doğrular.
  4. Cihaz kimlik doğrulaması (DeviceSigned):
    • Okuyucu, kimlik bilgisini sunan cihazın, imzalı MSO içinde yayınlanan DeviceKey ile eşleşen özel anahtara sahip olduğunu doğrular.
    • Bu işlem, SessionTranscript üzerinden DeviceAuth (DeviceSignature veya DeviceMac) doğrulanarak, oturum okuyucunun geçici anahtarına bağlanarak ve yeniden oynatma ile ortadaki adam saldırıları önlenerek 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 ve yerel bir güvenilir sertifika deposu bulundurmalıdır:

  • Üretim IACA Sertifikaları: Resmi sertifika yetkililerinden kök sertifikaları indirip yapılandırın. Desteklenen Verenler ve IACA Sertifikaları listemize bakın.
  • AAMVA VICAL: ABD yargı alanlarında okuyucu sistemleri, eyalet güven çapalarını otomatik olarak senkronize etmek için Amerikan Motorlu Araç Yöneticileri Birliği (AAMVA) Onaylı Veren Sertifika Yetkilisi Listesi (VICAL) hizmetiyle entegre edilebilir.
  • Korumalı Alan Test Kökleri: Korumalı alan kimlik bilgileriyle test yaparken okuyucunun Google Korumalı Alan IACA Kökü'ne 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ı, okuyucu uygulamasının, yetkili bir X.509 okuyucu sertifikası kullanarak ReaderAuthentication yapısını imzalayarak kimliğini Google Cüzdan'a 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ğrulaması) için isteğe bağlı olsa da kullanıcı güvenini artırmak amacıyla okuyucu entegrasyonlarında kesinlikle önerilir. Hassas özellikler (ör. tam vatandaşlık numarası, ikamet adresi veya belirli eyalet onayları) talep edilirken yasal olarak ya da politika gereği zorunlu olabilir.
  • İşleyiş şekli: Okuyucu, sertifika zincirini ekler ve oturum transkriptini imzalar. Google Cüzdan, veriler paylaşılmadan ö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ı kullanın:

  1. Multipaz Referans Uygulamaları:
    • Fiziksel doğrulama akışlarını test etmek için Multipaz deposunu klonlayın ve 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, talep sorgularını keşfetmek ve W3C / ISO 18013-7 web tabanlı sunuları 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ı / Bağlantı kurulamadı
  • 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 Merkezi İstemci hem de Çevre Birimi Sunucusu 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 anlaşmasının başarıyla tamamlandığını doğrulayın.
NFC dokunma etkileşimi başarısız oluyor veya kesiliyor Kullanıcı, BLE aktarım kaydı tamamen aktarılmadan önce mobil cihazı okuyucu anteninden uzaklaştırıyor.
  • NFC etkileşimi başlar başlamaz terminalde anında görsel/işitsel/dokunsal geribildirim sağlayın.
  • Kullanıcılara, BLE bağlantısı kurulana kadar telefonu NFC hedefine karşı sabit tutmalarını söyleyin.
UNTRUSTED_ISSUER / Sertifika zinciri hatası Belge imzalayan sertifikası, okuyucunun yerel güvenilir sertifika deposundaki herhangi bir güvenilir IACA sertifikasına bağlı değil.
  • Sertifikayı verenin kök sertifikasının, okuyucunun güvenilir sertifika deposuna yüklendiğinden emin olun.
  • 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
  • Okuyucu sistem saati senkronize değil.
  • MSO imzasının süresi doldu.
  • Okuyucu cihazın, sistem saatini NTP aracılığıyla 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 Okuyucu ile cüzdan arasında oturum transkripti uyuşmazlığı veya geçersiz geçici cihaz imzası.
  • DeviceEngagementBytes ve EReaderKeyBytes değerlerinin tam ham baytlarının, yeniden kodlama yapılmadan SessionTranscript yapısında korunduğundan emin olun.
Android 12 ve sonraki sürümlerde izinle ilgili kilitlenme Uygulama, çalışma zamanında istenen izinler olmadan BDE üzerinden tarama veya bildirme yapmaya çalıştı.
  • Okuyucu oturumlarını başlatmadan önce çalışma zamanında BLUETOOTH_SCAN, BLUETOOTH_CONNECT ve BLUETOOTH_ADVERTISE izinlerini kontrol edin ve isteyin.

Yüz Yüze Okuyucular İçin Kullanıcı Deneyimi ve Gizlilik Kuralları

Fiziksel okuyucuları ve tamamlayıcı uygulamaları tasarlarken:

  • Kullanıcı arayüzünde seçici paylaşım uygulayın: Operatöre yalnızca kararı veya gereken minimum özelliği gösterin (ör. kullanıcının tam doğum tarihini, adresini ve ehliyet numarasını göstermek yerine belirgin bir yeşil onay işareti ve "21 Yaş Üstü 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: Dokun / Tara → Bağlanıyor → Doğrulanıyor → Tamamlandı.
  • Geçici Veri İşleme: Geçerli yasalar uyarınca açıkça zorunlu kılınmadığı ve intentToRetain = true aracılığıyla açıklanmadığı sürece cüzdandan alınan kişisel veri öğelerini saklamayın veya kaydetmeyin.