アテステーション¶
この端末の署名キーを DEA に登録します。SDK は最初に必要になったときに、Android Keystore の中(端末が対応 していれば StrongBox の中)にキーを作成します。秘密鍵の半分はアプリからも SDK からも読み取れません。可能な場合、 登録には Google Play Integrity トークンも添付され、DEA は端末とアプリが正規のものかを確認できます。
DEA は appKey が属するアプリの下に登録を記録します。
アカウントとキーを参照してください。
使いどころ¶
- 機密性の高いステップの前に、端末が登録されていることを確認するとき
- 診断画面にアテステーションの状態を表示するとき
前提条件¶
- SDK がインストールされ、
appId、appKey、playIntegrityProjectで初期化されている。 クイックスタートとアカウントとキーを 参照してください。 - Android 6.0(API 23)以降。それ未満では
attest()はUNSUPPORTEDを返します。 - 下記の Play Integrity の設定。
プラットフォームのセットアップ¶
Play Integrity¶
Play は認識しているアプリ(Google Play からインストールされたもの、またはアプリの Play Console エントリに
登録されたキーで署名されたもの)にのみ正規のトークンを発行します。Play がトークンを発行しない場合(Google Play
開発者サービスのない端末や、Play が要求を拒否した場合)、SDK はトークンなしで登録を送信し、DEA はそれを拒否
することがあります。その場合 attest() は FAILED を返し、detail に DEA の回答が入ります。
DEA がアプリ用に発行した Google Cloud プロジェクト番号を playIntegrityProject として渡してください。これは
Play Console の「アプリの完全性」ページでアプリにリンクされているプロジェクトでなければなりません。他の番号では
attest() は FAILED を返します。アカウントとキーを参照してください。
DeaSdk.init(
this,
DeaConfig(appId = "YOUR_APP_ID", appKey = "YOUR_APP_KEY", playIntegrityProject = 123456789012L),
)
使い方¶
アテステーションを行う¶
attest() はネットワーク要求を行い、呼び出し元のスレッドをブロックするため、メインスレッド以外で呼び出して
ください。以下のサンプルは Kotlin のコルーチンを使っています。
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.attest.Verdict
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
suspend fun attestDevice() {
val attestation = withContext(Dispatchers.IO) { DeaSdk.instance?.attest() } ?: return
when (attestation.verdict) {
Verdict.PASSED -> {
// DEA accepted this device's key.
}
Verdict.UNSUPPORTED -> {
// No key could be created on this device, or no appKey was given. See attestation.detail.
}
Verdict.FAILED -> {
// DEA refused, or could not be reached. See attestation.detail.
}
}
}
attest()は例外を投げません。- 結果は期限が切れる少し前まで端末にキャッシュされ、アプリの再起動をまたいでも保持されるため、再度の呼び出しは 通常コストがかかりません。
- 最初の呼び出しで自動更新が有効になります。 以降、SDK は期限が切れる少し前に登録を更新し、アプリが
フォアグラウンドに戻るたびに再確認します。
attest()を一度も呼び出さないアプリは、キーを登録しません。 - Play Integrity トークンを使った登録が失敗した後、SDK は再試行まで待機します。最初は 1 時間、失敗を重ねる
ごとに倍増し、最長 7 日間です。アプリの再起動をまたいでも同様です。それまで
attest()は要求を行わずにFAILEDを返し、detailにいつまで待つかが示されます。
登録では、キーの公開鍵の半分、Play Integrity トークン(ある場合)、および SDK が検出した root 化・フック・ デバッグ・エミュレーターの兆候を示すコードを DEA に送信します。 プライバシーとネットワークを参照してください。
Play Integrity が含まれていたか確認する¶
PASSED の結果は DEA がキーを受け付けたことを意味します。受け付けられた登録に Play Integrity トークンが
添付されていた場合、platformAttested は true です。
if (attestation.verdict == Verdict.PASSED && attestation.platformAttested) {
// DEA accepted the key, with Google's token about the device and app.
}
integrity には、DEA が返した場合に、端末についての DEA 独自の判定が入ります。
再度アテステーションせずに最後の結果を読む¶
このインストールがすでに保持している登録(以前の起動で得たものを含む)を、要求を行わずに読むには次のようにします。
val stored = withContext(Dispatchers.IO) { DeaSdk.instance?.storedAttestation() } // null if none is fresh
storedAttestation() は端末のストレージを読みます。有効な登録が見つかると、attest() と同様に自動更新を
有効にします。
今すぐ更新する¶
renewAttestation() は、キャッシュされた結果がまだ有効でも、すぐに再登録します。更新が失敗した場合、
すでに保持している登録はそのまま残ります。登録が拒否された後の待機中は、attest() と同様に要求を行わずに
FAILED を返します。attest() と同様にブロックします。
やり直す¶
保存された登録と、拒否された試行の後の待機を忘れ、自動更新を停止します。端末キーは維持されるため、次の
attest() は同じキーを再登録します。
自動更新を監視する¶
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.attest.AttestRefresher
import android.util.Log
val dea = DeaSdk.instance!!
// Set before the first attest(), which reports the first schedule.
dea.onAttestationEvent = { event ->
when (event) {
is AttestRefresher.Event.Scheduled -> Log.d("MyApp", "renewal in ${event.afterSeconds} s")
is AttestRefresher.Event.Fired -> Log.d("MyApp", "renewed: ${event.verdict}")
AttestRefresher.Event.Idle -> Log.d("MyApp", "nothing to renew")
}
}
Log.d("MyApp", "next renewal at ${dea.nextAttestationRefresh}") // epoch seconds, or null
コールバックは判断を行ったスレッドで実行され、それは必ずしもメインスレッドではありません。
例¶
決済画面を開く前にアテステーションを行う¶
import ai.dea.sdk.DeaSdk
import ai.dea.sdk.attest.Verdict
import android.content.Intent
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
fun AppCompatActivity.openPayment() {
lifecycleScope.launch {
val attestation = withContext(Dispatchers.IO) { DeaSdk.instance?.attest() }
if (attestation?.verdict != Verdict.PASSED) {
Log.w("MyApp", "DEA attestation: $attestation")
}
startActivity(Intent(this@openPayment, PaymentActivity::class.java))
}
}
API¶
| メンバー | 戻り値 | 説明 |
|---|---|---|
attest() |
Attestation |
端末キーを登録し、結果を返します。ブロックします |
renewAttestation() |
Attestation |
今すぐ再登録します。ブロックします |
lastAttestation |
Attestation? |
再度アテステーションせずに読める最後の結果 |
storedAttestation() |
Attestation? |
このインストールが保持する有効な登録。要求を行わずにストレージから読みます |
forgetAttestation() |
Unit |
登録を忘れ、自動更新を停止します。キーは維持します |
nextAttestationRefresh |
Long? |
次の自動更新が実行される時刻(エポック秒) |
onAttestationEvent |
((AttestRefresher.Event) -> Unit)? |
自動更新の判断ごとに呼び出されます |
Attestation:
| フィールド | 型 | 説明 |
|---|---|---|
supported |
Boolean |
SDK が登録できたかどうか。キーを作成できなかった場合、または appKey が指定されていない場合は false |
verdict |
Verdict |
PASSED、FAILED、UNSUPPORTED のいずれか |
platformAttested |
Boolean |
受け付けられた登録に Play Integrity トークンが添付されていたかどうか |
platformTokenSpent |
Boolean |
DEA の回答にかかわらず、この試行で Play Integrity トークンを取得したかどうか |
integrity |
String? |
DEA が返した場合の、端末の完全性についての DEA の判定 |
expiresAt |
Long? |
有効期限(エポック秒) |
kid |
String? |
キーの識別子 |
tier |
String? |
DEA が割り当てた信頼ティア |
backing |
String? |
キーの保管場所: strongbox、tee、software のいずれか |
detail |
String? |
SDK が登録しなかった理由、または失敗時に DEA やネットワークが返した内容 |