コンテンツにスキップ

アテステーション

この端末の署名キーを DEA に登録します。SDK は最初に必要になったときにキーを作成します。端末に Secure Enclave があればその中に作成するため、秘密鍵の側はアプリからも SDK からも読み取れません。端末が対応 している場合、登録には Apple の App Attest トークンも含まれ、DEA は端末とアプリが正規のものであることを 確認できます。さらに、SDK が見つけたジェイルブレイクや改変の兆候(ジェイルブレイクのファイルやデバッガー など)を短いコードとして含めます。ファイルパスやアプリ名は決して含めません。

使いどころ

  • 機密性の高いステップの前に、端末が登録されていることを確認する
  • 診断画面にアテステーションの状態を表示する

前提条件

  • SDK がインストールされ、開始されている。クイックスタートを参照してください。
  • DEA がこの iOS アプリ向けに発行した appKey を、appKey として渡している。これがないと attest() は .unsupported を返し、どこにも接続しません。 アカウントとキーを参照してください。
  • 以下のプラットフォームのセットアップ。

プラットフォームのセットアップ

App Attest

アプリに App Attest ケイパビリティを追加します。

  1. Xcode でプロジェクトを開きます。
  2. アプリのターゲットを選択し、Signing & Capabilities を開きます。
  3. + Capability をクリックして App Attest を追加します。

これにより com.apple.developer.devicecheck.appattest-environment エンタイトルメントが追加されます。 App Attest には iOS 14 以降が必要で、iOS シミュレーターでは利用できません。シミュレーター、古い端末、 App Attest のない端末では、SDK は App Attest トークンなしでキーを送ります。

使い方

アテステーションを行う

attest() はネットワーク要求を行い、それが終わるまで呼び出し元のスレッドをブロックします(要求 ごとに最大約 15 秒、App Attest にもさらに同程度)。メインスレッドでは決して呼び出さないでください。

import DeaSDK

Task.detached {
    guard let attestation = Dea.sdk?.attest() else { return }

    switch attestation.verdict {
    case .passed:
        // DEA accepted this device's key.
        break
    case .unsupported:
        // No key could be created on this device, or no appKey was given.
        print("DEA attestation unsupported: \(attestation.detail ?? "no device key")")
    case .failed:
        // DEA refused, could not be reached, or App Attest refused. See attestation.detail.
        print("DEA attestation failed: \(attestation.detail ?? "")")
    }
}
  • attest() は決して throw しません。
  • 合格した結果は起動をまたいでも、期限切れの直前までキャッシュされるため、再度呼び出してもコストは かかりません。
  • 最初の attest() の後、SDK は期限切れの直前に自動で登録を更新します。アプリがフォアグラウンドに 戻ったときも同様です。attest() を一度も呼び出さないアプリはキーを登録せず、アテステーションの 要求も行いません。
  • App Attest トークンを使った登録を DEA が拒否した後、attest() はしばらくの間 DEA に接続せずに .failed を返します。最初は 1 時間で、連続して拒否されるごとに倍になり、最長 7 日です。detail に いつまでかが示されます。Apple は端末上のこのアプリの App Attest アテステーションをすべて数えるため、 DEA が拒否し続ける登録に SDK がそれを費やすことはありません。

プラットフォームが端末を保証したかを確認する

passed の結果は DEA がキーを受け付けたことを意味します。それが端末についての言明になるのは、 platformAttested が true のときだけです。

if attestation.verdict == .passed && attestation.platformAttested {
    // Apple confirmed the device and app.
}

platformAttested は、登録が App Attest トークンなしで送られた場合に false です。シミュレーター、 iOS 14 より古い端末や App Attest のない端末、App Attest が時間内に応答しなかった場合です。

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

let last = Dea.sdk?.lastAttestation // nil before the first attest()

DEA に接続せずに登録を確認する

Task.detached {
    if let stored = Dea.sdk?.storedAttestation() {
        print("Already registered until \(stored.expiresAt ?? 0)")
    }
}

storedAttestation() は、このインストールがすでに保持している登録を、まだ有効であれば、ネットワーク 要求も App Attest の使用もなしに返します。nil は attest() が再登録する必要があることを意味します。 キーチェーンを読み取るため、メインスレッド以外で呼び出してください。この方法で見つかった登録は、 attest() の後と同様に自動で更新されます。

今すぐ更新する

Task.detached {
    if let renewed = Dea.sdk?.renewAttestation() {
        print("DEA attestation renewed: \(renewed.verdict)")
    }
}

renewAttestation() は、現在の結果がまだ有効でも再登録します。たとえば機密性の高いステップの直前です。 更新に失敗した場合は、以前の有効な結果が保持されます。attest() と同様にブロックするため、メインスレッド 以外で呼び出してください。

やり直す

Task.detached {
    Dea.sdk?.forgetAttestation()
}

forgetAttestation() は、このインストールの登録と、拒否された試行の後の待機を忘れるため、次の attest() は最初から登録します。端末キーは保持されます。自動更新は次の attest() まで停止します。進行中の attest() を待つため、メインスレッド以外で呼び出してください。

例

支払いステップの前にアテステーションを行う(SwiftUI)

import DeaSDK
import SwiftUI

struct CheckoutButton: View {
    @State private var showPayment = false

    var body: some View {
        Button("Pay") {
            Task {
                let attestation = await Task.detached { Dea.sdk?.attest() }.value
                if attestation?.verdict != .passed {
                    print("DEA attestation: \(String(describing: attestation))")
                }
                showPayment = true
            }
        }
        .sheet(isPresented: $showPayment) {
            PaymentView()
        }
    }
}

起動時にアテステーションを行う(UIKit)

import DeaSDK
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Dea.start()
        DispatchQueue.global(qos: .utility).async {
            _ = Dea.sdk?.attest()
        }
        return true
    }
}

API

メンバー 戻り値 説明
attest() Attestation 端末キーを登録し、結果を返す。ブロックする
renewAttestation() Attestation 今すぐ再登録する。失敗時は以前の結果を保持する。ブロックする
storedAttestation() Attestation? このインストールが保持する有効な登録。ネットワーク要求なし
forgetAttestation() Void 登録を忘れ、次の attest() が最初から登録するようにする
lastAttestation Attestation? 再度アテステーションせずに読める最後の結果
nextAttestationRefresh Date? 自動更新が次に実行される時刻
appKey String? SDK が送るアプリキー。渡されていない場合は nil

Attestation:

フィールド 型 説明
supported Bool この端末でキーを作成でき、appKey が渡されているかどうか
verdict Attestation.Verdict .passed、.failed、.unsupported のいずれか
platformAttested Bool App Attest トークンがキーとともに送られ、DEA が受け付けたかどうか
platformTokenSpent Bool 結果にかかわらず、この試行で App Attest アテステーションを使ったかどうか
expiresAt Int? 期限(エポック秒)
kid String? キーの識別子
tier String? DEA が割り当てた信頼ティア
integrity String? DEA の応答に含まれる場合、端末の整合性についての DEA の判定
backing String? キーの保管場所: secure_enclave または software
detail String? アテステーションが合格しなかった場合、その理由