アテステーション¶
この端末の署名キーを DEA に登録します。SDK は最初に必要になったときに、Android Keystore または iOS の Secure Enclave の中にキーを作成します。秘密鍵の側はアプリからも SDK からも読み取れません。SDK はこの キーとともに Google Play Integrity トークン(Android)または Apple App Attest トークン(iOS)を送信し、 DEA はキーを受け入れる前に端末とアプリが正規のものであることを確認できます。
使いどころ¶
- 機密性の高いステップの前に、端末が登録済みであることを確認する
- 診断画面にアテステーションの状態を表示する
前提条件¶
- SDK がインストールされ、初期化されている。クイックスタートを参照してください。
- このプラットフォームのアプリに対して DEA が発行した値が
DeaSdk.initに渡されている。両プラットフォーム でappIdとappKey、Android では加えてplayIntegrityProject。 オプションを参照してください。 - 以下のプラットフォームのセットアップ。
プラットフォームのセットアップ¶
Android: Play Integrity¶
Android アプリに対して DEA が発行した Google Cloud プロジェクト番号を playIntegrityProject として
渡します。これは Play Console の「アプリの整合性」ページでアプリにリンクされているプロジェクトで
なければなりません。別の番号を渡すと、attest() は failed を返します。
DEA のサービスは、キーを受け入れる前にトークンを読み取ります。Google Play がそのアプリを認識して いること、このコピーが Google Play 経由でインストールされたこと、端末が Play の端末整合性チェックを 満たしていることが必要です。したがって、ファイルからインストールされたビルドや、アプリの Play Console エントリに登録されていないキーで署名されたビルドはアテステーションに失敗します。Google Play の テストトラックからのビルドを、Google Play 開発者サービスのある実機でテストしてください。
DeaSdk.init(
const DeaOptions(appId: 'YOUR_APP_ID'),
appKey: 'YOUR_APP_KEY',
playIntegrityProject: 123456789012, // read on Android only
);
iOS: App Attest¶
アプリに App Attest ケイパビリティを追加します:
- Xcode で
ios/Runner.xcworkspaceを開きます。 - Runner ターゲットを選択し、Signing & Capabilities を開きます。
- + Capability をクリックして App Attest を追加します。
これにより、com.apple.developer.devicecheck.appattest-environment エンタイトルメントが値
development(Apple の App Attest サンドボックス)で追加されます。Xcode から実行するビルドはこれを
使います。TestFlight、App Store、または Apple Developer Enterprise Program 経由で配布されるビルドは
この値を無視し、Apple の本番環境を使います。ケイパビリティがないと App Attest はすべてのキーを拒否
します。attest() は failed を返し、attestation.detail には通常 invalidKey が含まれます。
App Attest には iOS 14 以降の実機が必要です。iOS シミュレーター、および iOS 12 と 13 では、SDK は
App Attest トークンなしで登録を送信するため、platformAttested は false になります。
使い方¶
アテステーションを行う¶
import 'package:dea_sdk/dea_sdk.dart';
final attestation = await DeaSdk.instance!.attest();
switch (attestation.verdict) {
case Verdict.passed:
// DEA accepted this device's key.
break;
case Verdict.unsupported:
// No key could be created on this device, or no appKey was given. See attestation.detail.
break;
case Verdict.failed:
// DEA refused, could not be reached, or the platform would not issue its token.
// See attestation.detail.
break;
}
attest()は決して例外を投げません。passedの結果は、有効期限の 1 分前まで端末上にも保持されるため、それまではattest()を再度呼んでも コストはかかりません。failedまたはunsupportedの結果は保持されず、次の呼び出しで再試行します。- 例外が 1 つあります。プラットフォームトークン付きの登録を DEA が拒否した後、SDK は Google または
Apple に次のトークンを求めるまで待ちます。最初は 1 時間で、拒否されるごとに倍になり、最長 7 日です。
その間、
attest()はどこにも接続せずにfailedを返し、detailにいつまで待つかが記されます。
プラットフォームトークンが送られたかを確認する¶
platformAttested は、Play Integrity または App Attest のトークンがキーとともに DEA に送られたかどうか
を示します:
if (attestation.verdict == Verdict.passed && attestation.platformAttested) {
// DEA accepted the key together with Google's or Apple's token.
}
プラットフォームが渡せるトークンを持たなかった場合(iOS シミュレーター、および iOS 12 と 13)は
false です。Google または Apple がトークンの発行を拒否した場合は、代わりに attest() が failed を
返し、detail にプラットフォーム側の理由が入ります。
再度アテステーションせずに最後の結果を読み取る¶
attestation は、この実行中に最後の attest() が返した結果で、拒否も含みます。
DEA に接続せずに既存の登録を確認する¶
final stored = await DeaSdk.instance?.storedAttestation();
// null: attest() would have to register the device again
storedAttestation() は、ネットワーク要求を行わず、Google や Apple にトークンを求めることもなく、端末に
保持されている登録を読み取ります。登録がない場合、または期限切れ間近の場合は null を返します。
例¶
決済ステップの前にアテステーションを行う¶
import 'package:dea_sdk/dea_sdk.dart';
import 'package:flutter/material.dart';
Future<void> openPayment(BuildContext context) async {
final attestation = await DeaSdk.instance?.attest();
if (attestation?.verdict != Verdict.passed) {
debugPrint('DEA attestation: $attestation, ${attestation?.detail}');
}
if (context.mounted) {
Navigator.of(context).pushNamed('/payment');
}
}
API¶
| メンバー | 戻り値 | 説明 |
|---|---|---|
attest() |
Future<Attestation> |
端末キーを登録し、結果を返す |
attestation |
Attestation? |
この実行中の最後の結果。再度アテステーションはしない |
storedAttestation() |
Future<Attestation?> |
端末に保持されている登録(まだ有効な場合)。ネットワークなし |
forgetAttestation() |
Future<void> |
登録を忘れ、次の attest() で再登録する |
Attestation:
| フィールド | 型 | 説明 |
|---|---|---|
supported |
bool |
この端末でキーを作成できたかどうか。appKey が渡されなかった場合も false |
verdict |
Verdict |
passed、failed、または unsupported |
platformAttested |
bool |
Play Integrity または App Attest のトークンがキーとともに DEA に送られたかどうか |
expiresAt |
int? |
有効期限(エポック秒) |
kid |
String? |
キーの識別子 |
tier |
String? |
DEA が割り当てた信頼ティア |
backing |
String? |
端末上でキーが保持されている場所: strongbox、tee、secure_enclave、または software |
integrity |
String? |
DEA による端末の整合性の読み取り。DEA のサービスは現時点では送信しないため null |
detail |
String? |
アテステーションが失敗した、または未サポートである理由 |