Android Sistemi Anahtar Doğrulayıcı

Android için Anahtar Doğrulayıcı, kullanıcıların uçtan uca şifrelenmiş (E2EE) uygulamanızda doğru kişiyle iletişim kurduklarını doğrulamaları için birleşik ve güvenli bir yol sunar. Kullanıcıların, güvenilir ve tutarlı bir sistem kullanıcı arayüzü aracılığıyla bir kişinin ortak şifreleme anahtarlarının gerçekliğini onaylamasına olanak tanıyarak kullanıcıları ortadaki adam saldırılarına karşı korur.

Bu özellik, Google Sistem Hizmetleri'nin bir parçası olan ve Play Store kullanılarak dağıtılan bir sistem hizmeti olan Anahtar Doğrulayıcı tarafından sağlanır. E2EE ortak anahtarları için merkezi bir cihaz içi depo görevi görür.

Neden Anahtar Doğrulayıcı ile entegrasyon yapmalısınız?

• Birleşik bir kullanıcı deneyimi sunun: Kendi doğrulama akışınızı oluşturmak yerine sistemin standart kullanıcı arayüzünü başlatarak kullanıcılara tüm uygulamalarında tutarlı ve güvenilir bir deneyim sunabilirsiniz.
• Kullanıcı güvenini artırma: Sistem tarafından desteklenen net bir doğrulama durumu, kullanıcılara görüşmelerinin güvenli ve gizli olduğu konusunda güvence verir.
• Geliştirme ek yükünü azaltma: Anahtar doğrulama kullanıcı arayüzü, depolama ve durum yönetimiyle ilgili karmaşıklığı sistem hizmetine aktarın.

Önemli: Bu hizmet, anahtarları doğrulamak için kullanılır ve şifreleme sağlamaz. Uygulamanız, kullanıcının cihazında depolanan anahtarlarla E2EE'yi zaten uygulamış olmalıdır.

Anahtar terimler

• lookupKey: Kişiler sağlayıcısının LOOKUP_KEY sütununda depolanan, kişi için opak ve kalıcı bir tanımlayıcı. contact ID'dan farklı olarak, temel iletişim bilgileri değiştirilse veya birleştirilse bile lookupKey sabit kalır. Bu nedenle, bir kişiye referans vermenin önerilen yoludur.
• accountId: Bir kullanıcının cihazdaki hesabı için uygulamaya özel tanımlayıcı. Bu kimlik, uygulamanız tarafından tanımlanır ve tek bir kullanıcının sahip olabileceği birden fazla hesap arasında ayrım yapılmasına yardımcı olur. Bu, kullanıcıya kullanıcı arayüzünde gösterilir. Telefon numarası, e-posta adresi veya kullanıcı adı gibi anlamlı bir şey kullanmanız önerilir.
• deviceId: Bir kullanıcının hesabıyla ilişkili belirli bir cihazın benzersiz tanımlayıcısı. Bu sayede kullanıcılar, her biri kendi şifreleme anahtarı grubuna sahip birden fazla cihaz kullanabilir. Fiziksel bir cihazı temsil etmeyebilir ancak aynı hesap için kullanılan birden fazla anahtarı ayırt etmenin bir yolu olabilir.

Başlarken

Başlamadan önce uygulamanızı KeyVerifier hizmetiyle iletişim kuracak şekilde ayarlayın.

İzinleri beyan edin: AndroidManifest.xml dosyanızda aşağıdaki izinleri beyan edin. Bunları çalışma zamanında kullanıcıdan da istemeniz gerekir.

<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

İstemci örneğini alma: API'ye giriş noktanız olan ContactKeys örneğini alın.

import com.google.android.gms.contactkeys.ContactKeys

val contactKeyClient = ContactKeys.getClient(context)

Mesajlaşma uygulaması geliştiricileri için rehberlik

Mesajlaşma uygulaması geliştiricisi olarak birincil göreviniz, kullanıcılarınızın genel anahtarlarını ve kişilerinin anahtarlarını Anahtar Doğrulayıcı hizmetinde yayınlamaktır.

Kullanıcının ortak anahtarlarını yayınlama

Diğer kullanıcıların, kullanıcılarınızı bulup doğrulayabilmesi için bu kullanıcıların genel anahtarını cihazdaki depoda yayınlayın. Daha fazla güvenlik için anahtarları Android Keystore'da oluşturabilirsiniz.

import com.google.android.gms.contactkeys.ContactKeyClient
import com.google.android.gms.tasks.Tasks

suspend fun publishSelfKey(
    contactKeyClient: ContactKeyClient,
    accountId: String,
    deviceId: String,
    publicKey: ByteArray
) {
    try {
        Tasks.await(
          contactKeyClient.updateOrInsertE2eeSelfKey(
            deviceId,
            accountId,
            publicKey
          )
        )
        // Self key published successfully.
    } catch (e: Exception) {
        // Handle error.
    }
}

Ortak anahtarları kişilerle ilişkilendirme

Uygulamanız, kullanıcının kişilerinden birinin ortak anahtarını aldığında bu anahtarı saklamanız ve merkezi depoda ilgili kişiyle ilişkilendirmeniz gerekir. Bu sayede anahtar doğrulanabilir ve diğer uygulamalar, kişinin doğrulama durumunu gösterebilir. Bunu yapmak için Android Kişiler Sağlayıcı'dan ilgili kişinin lookupKey değerini almanız gerekir. Bu durum genellikle anahtar dağıtım sunucunuzdan anahtar alınırken veya yerel anahtarların periyodik senkronizasyonu sırasında tetiklenir.

import com.google.android.gms.contactkeys.ContactKeyClient
import com.google.android.gms.tasks.Tasks

suspend fun storeContactKey(
    contactKeyClient: ContactKeyClient,
    contactLookupKey: String,
    contactAccountId: String,
    contactDeviceId: String,
    contactPublicKey: ByteArray
) {
    try {
        Tasks.await(
            contactKeyClient.updateOrInsertE2eeContactKey(
                contactLookupKey,
                contactDeviceId,
                contactAccountId,
                contactPublicKey
            )
        )
        // Contact's key stored successfully.
    } catch (e: Exception) {
        // Handle error.
    }
}

Not: Arama anahtarlarının listesini kabul eden updateOrInsertE2eeContactKey aşırı yüklemesini kullanarak bir anahtarı birden fazla kişiyle ilişkilendirebilirsiniz.

Anahtarları ve doğrulama durumunu alma

Anahtarları yayınladıktan sonra kullanıcılar, yüz yüze QR kodu taraması yaparak anahtarları doğrulayabilir. Uygulamanızın kullanıcı arayüzü, bir görüşmede doğrulanmış anahtarın kullanılıp kullanılmadığını yansıtmalıdır. Her anahtarın, kullanıcı arayüzünüzü bilgilendirmek için kullanabileceğiniz bir doğrulama durumu vardır.

Doğrulama durumlarını anlama:

• UNVERIFIED: Bu, her yeni anahtarın varsayılan durumudur. Bu, anahtarın mevcut olduğu ancak kullanıcının henüz anahtarın gerçekliğini onaylamadığı anlamına gelir. Kullanıcı arayüzünüzde bunu tarafsız bir durum olarak değerlendirmeli ve genellikle özel bir gösterge göstermemelisiniz.

• VERIFIED: Bu durum, yüksek düzeyde güven olduğunu gösterir. Bu, kullanıcının bir doğrulama akışını (ör. QR kodu tarama) başarıyla tamamladığı ve anahtarın amaçlanan kişiye ait olduğunu onayladığı anlamına gelir. Kullanıcı arayüzünüzde yeşil onay işareti veya kalkan gibi net ve olumlu bir gösterge göstermelisiniz.

• VERIFICATION_FAILED: Bu bir uyarı durumudur. Bu, ilgili kişiyle ilişkili anahtarın daha önce doğrulanmış anahtarla eşleşmediği anlamına gelir. Bu durum, bir kişi yeni bir cihaz aldığında ortaya çıkabilir ancak olası bir güvenlik riskinin de işareti olabilir. Kullanıcı arayüzünüzde, kullanıcıyı belirgin bir uyarı ile uyarın ve hassas bilgileri göndermeden önce yeniden doğrulama yapmasını önerin.

Bir kişiyle ilişkili tüm anahtarların toplu durumunu alabilirsiniz. Birden fazla anahtar olduğunda durumu çözmek için VerificationState.leastVerifiedFrom() kullanmanızı öneririz. Bu durumda VERIFICATION_FAILED, VERIFIED üzerinde doğru şekilde önceliklendirilir.

• Kişi düzeyinde toplu durumu alma

import com.google.android.gms.contactkeys.ContactKeyClient
import com.google.android.gms.contactkeys.constants.VerificationState
import com.google.android.gms.tasks.Tasks

suspend fun displayContactVerificationStatus(
    contactKeyClient: ContactKeyClient,
    contactLookupKey: String
) {
    try {
        val keysResult = Tasks.await(contactKeyClient.getAllE2eeContactKeys(contactLookupKey))
        val states =
          keysResult.keys.map { VerificationState.fromState(it.localVerificationState) }
        val contactStatus = VerificationState.leastVerifiedFrom(states)
        updateUi(contactLookupKey, contactStatus)
    } catch (e: Exception) {
        // Handle error.
    }
}

• Hesap düzeyinde toplu durum alma

import com.google.android.gms.contactkeys.ContactKeyClient
import com.google.android.gms.contactkeys.constants.VerificationState
import com.google.android.gms.tasks.Tasks

suspend fun displayAccountVerificationStatus(
    contactKeyClient: ContactKeyClient,
    accountId: String
) {
    try {
        val keys = Tasks.await(contactKeyClient.getE2eeAccountKeysForAccount(accountId))
        val states = keys.map { VerificationState.fromState(it.localVerificationState) }
        val accountStatus = VerificationState.leastVerifiedFrom(states)
        updateUi(accountId, accountStatus)
    } catch (e: Exception) {
        // Handle error.
    }
}

Önemli değişiklikleri anlık olarak gözlemleme

Uygulamanızın kullanıcı arayüzünde her zaman doğru güven durumunun gösterildiğini doğrulamak için güncellemeleri dinlemeniz gerekir. Önerilen yöntem, Flow tabanlı API'yi kullanmaktır. Bu API, abone olunan bir hesabın anahtarı eklendiğinde, kaldırıldığında veya doğrulama durumu değiştirildiğinde yeni bir anahtar listesi oluşturur. Bu özellik, özellikle grup sohbetlerinin üye listesini güncel tutmak için yararlıdır. Bir anahtarın doğrulama durumu şu durumlarda değişebilir:

• Kullanıcı, doğrulama akışını (ör. QR kodu tarama) başarıyla tamamlar.
• Bir kişinin anahtarı değiştirildiğinden artık daha önce doğrulanmış değerle eşleşmiyor.

fun observeKeyUpdates(contactKeyClient: ContactKeyClient, accountIds: List<String>) {
    lifecycleScope.launch {
        contactKeyClient.getAccountContactKeysFlow(accountIds)
            .collect { updatedKeys ->
                // A key was added, removed, or updated.
                // Refresh your app's UI and internal state.
                refreshUi(updatedKeys)
            }
    }
}

Yüz yüze anahtar doğrulama gerçekleştirme

Kullanıcıların anahtarı doğrulamasının en güvenli yolu, genellikle QR kodu tarayarak veya bir sayı dizisini karşılaştırarak yapılan yüz yüze doğrulama işlemidir. Key Verifier uygulaması, bu işlem için standart kullanıcı arayüzü akışları sağlar. Uygulamanız bu akışları başlatabilir. Doğrulama denemesinden sonra API, anahtarın doğrulama durumunu otomatik olarak günceller ve anahtar güncellemelerini izliyorsanız uygulamanız bilgilendirilir.

• Kullanıcı tarafından seçilen bir kişi için anahtar doğrulama sürecini başlatma Seçilen kişinin lookupKey bilgisini kullanarak getScanQrCodeIntent tarafından sağlanan PendingIntent uygulamasını başlatın. Kullanıcı arayüzü, kullanıcının belirli bir kişi için tüm anahtarları doğrulamasını sağlar.

import android.app.ActivityOptions
import android.app.PendingIntent
import com.google.android.gms.contactkeys.ContactKeyClient
import com.google.android.gms.tasks.Tasks

suspend fun initiateVerification(contactKeyClient: ContactKeyClient, lookupKey: String) {
    try {
        val pendingIntent = Tasks.await(contactKeyClient.getScanQrCodeIntent(lookupKey))
        val options =
          ActivityOptions.makeBasic()
            .setPendingIntentBackgroundActivityStartMode(
              ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
            )
            .toBundle()
        pendingIntent.send(options)
    } catch (e: Exception) {
        // Handle error.
    }
}

• Kullanıcı tarafından seçilen bir hesap için anahtar doğrulama sürecini başlatma Kullanıcı, doğrudan bir kişiye bağlı olmayan bir hesabı (veya bir kişinin belirli bir hesabını) doğrulamak istiyorsa PendingIntent tarafından sağlanangetScanQrCodeIntentForAccount doğrulama sürecini başlatabilirsiniz. Bu genellikle kendi uygulamanızın paket adı ve hesap kimliği için kullanılır.

import android.app.ActivityOptions
import android.app.PendingIntent
import com.google.android.gms.contactkeys.ContactKeyClient
import com.google.android.gms.tasks.Tasks

suspend fun initiateVerification(contactKeyClient: ContactKeyClient, packageName: String, accountId: String) {
    try {
        val pendingIntent = Tasks.await(contactKeyClient.getScanQrCodeIntentForAccount(packageName, accountId))
        // Allow activity start from background on Android SDK34+
        val options =
          ActivityOptions.makeBasic()
            .setPendingIntentBackgroundActivityStartMode(
              ActivityOptions.MODE_BACKGROUND_ACTIVITY_START_ALLOWED
            )
            .toBundle()
        pendingIntent.send(options)
    } catch (e: Exception) {
        // Handle error.
    }
}