コンテンツにスキップ

アテステーション

この端末の署名キーを 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 ケイパビリティを追加します:

  1. Xcode で ios/Runner.xcworkspace を開きます。
  2. Runner ターゲットを選択し、Signing & Capabilities を開きます。
  3. + 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 にプラットフォーム側の理由が入ります。

再度アテステーションせずに最後の結果を読み取る

final last = DeaSdk.instance?.attestation; // null before the first attest() in this run

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? アテステーションが失敗した、または未サポートである理由