アテステーション¶
この端末の署名キーを DEA に登録します。SDK は最初に必要になったときにキーを作成します。端末に Secure Enclave があればその中に作成するため、秘密鍵の側はアプリからも SDK からも読み取れません。端末が対応 している場合、登録には Apple の App Attest トークンも含まれ、DEA は端末とアプリが正規のものであることを 確認できます。さらに、SDK が見つけたジェイルブレイクや改変の兆候(ジェイルブレイクのファイルやデバッガー など)を短いコードとして含めます。ファイルパスやアプリ名は決して含めません。
使いどころ¶
- 機密性の高いステップの前に、端末が登録されていることを確認する
- 診断画面にアテステーションの状態を表示する
前提条件¶
- SDK がインストールされ、開始されている。クイックスタートを参照してください。
- DEA がこの iOS アプリ向けに発行した
appKeyを、appKeyとして渡している。これがないとattest()は.unsupportedを返し、どこにも接続しません。 アカウントとキーを参照してください。 - 以下のプラットフォームのセットアップ。
プラットフォームのセットアップ¶
App Attest¶
アプリに App Attest ケイパビリティを追加します。
- Xcode でプロジェクトを開きます。
- アプリのターゲットを選択し、Signing & Capabilities を開きます。
- + 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 が時間内に応答しなかった場合です。
再度アテステーションせずに最後の結果を読み取る¶
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() と同様にブロックするため、メインスレッド
以外で呼び出してください。
やり直す¶
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? |
アテステーションが合格しなかった場合、その理由 |