コンテンツにスキップ

アテステーション

この端末の署名キーを 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 last = DeaSdk.instance?.lastAttestation // null before the first attest()

このインストールがすでに保持している登録(以前の起動で得たものを含む)を、要求を行わずに読むには次のようにします。

val stored = withContext(Dispatchers.IO) { DeaSdk.instance?.storedAttestation() } // null if none is fresh

storedAttestation() は端末のストレージを読みます。有効な登録が見つかると、attest() と同様に自動更新を 有効にします。

今すぐ更新する

val renewed = withContext(Dispatchers.IO) { DeaSdk.instance?.renewAttestation() }

renewAttestation() は、キャッシュされた結果がまだ有効でも、すぐに再登録します。更新が失敗した場合、 すでに保持している登録はそのまま残ります。登録が拒否された後の待機中は、attest() と同様に要求を行わずに FAILED を返します。attest() と同様にブロックします。

やり直す

DeaSdk.instance?.forgetAttestation()

保存された登録と、拒否された試行の後の待機を忘れ、自動更新を停止します。端末キーは維持されるため、次の 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 やネットワークが返した内容