objc2_device_check/generated/DCAppAttestService.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7
8use crate::*;
9
10extern_class!(
11 /// A service that you use to validate the instance of your app running on a
12 /// device.
13 ///
14 /// Use the ``DeviceCheck/DCAppAttestService/sharedService`` instance of the
15 /// ``DeviceCheck/DCAppAttestService`` class to assert the legitimacy of a
16 /// particular instance of your app to your server. After ensuring service
17 /// availability by reading the ``DeviceCheck/DCAppAttestService/supported``
18 /// property, you use the service to:
19 ///
20 /// - Create a cryptographic key in the Secure Enclave by calling the
21 /// ``DeviceCheck/DCAppAttestService/generateKeyWithCompletionHandler:`` method.
22 /// - Ask Apple to certify the key by calling the
23 /// ``DeviceCheck/DCAppAttestService/attestKey:clientDataHash:completionHandler:``
24 /// method. - Prepare an assertion of your app’s integrity to accompany any or
25 /// all server requests using the
26 /// ``DeviceCheck/DCAppAttestService/generateAssertion:clientDataHash:completionHandler:``
27 /// method.
28 ///
29 /// For more information about how to support App Attest in your app, see
30 /// <doc
31 /// :establishing-your-app-s-integrity>. For information about the
32 /// complementary procedures you implement on your server, see
33 /// <doc
34 /// :validating-apps-that-connect-to-your-server>.
35 ///
36 /// - Note: To use the App Attest service, your app must have an app ID that you
37 /// register on the [Apple Developer](https://developer.apple.com/account/)
38 /// website.
39 ///
40 /// See also [Apple's documentation](https://developer.apple.com/documentation/devicecheck/dcappattestservice?language=objc)
41 #[unsafe(super(NSObject))]
42 #[derive(Debug, PartialEq, Eq, Hash)]
43 pub struct DCAppAttestService;
44);
45
46unsafe impl NSObjectProtocol for DCAppAttestService {}
47
48impl DCAppAttestService {
49 extern_methods!(
50 /// The shared App Attest service that you use to validate your app.
51 ///
52 /// Use the shared instance of the service to generate and to certify a
53 /// cryptographic key, and then to assert your app’s validity using that key.
54 #[unsafe(method(sharedService))]
55 #[unsafe(method_family = none)]
56 pub unsafe fn sharedService() -> Retained<DCAppAttestService>;
57
58 /// A Boolean value that indicates whether a particular device provides the App
59 /// Attest service.
60 ///
61 /// > Important: Not all device types support the App Attest service, so check
62 /// > for support before using the service.
63 /// >
64 /// > If you read ``DeviceCheck/DCAppAttestService/supported`` from an app running
65 /// > on a Mac device, the value is
66 /// >
67 /// <doc
68 /// ://com.apple.documentation/documentation/swift/false>. This includes
69 /// > Mac Catalyst apps, and iOS or iPadOS apps running on Apple silicon.
70 ///
71 /// If you read ``DeviceCheck/DCAppAttestService/supported`` from within an app
72 /// extension, the value might be
73 /// <doc
74 /// ://com.apple.documentation/documentation/swift/true> or
75 /// <doc
76 /// ://com.apple.documentation/documentation/swift/false>, depending on
77 /// the extension type. However, most extensions don’t support App Attest. The
78 /// ``DeviceCheck/DCAppAttestService/generateKeyWithCompletionHandler:`` method
79 /// fails when you call it from an app extension, regardless of the value of
80 /// ``DeviceCheck/DCAppAttestService/supported``.
81 ///
82 /// The only app extensions that support App Attest are watchOS extensions in
83 /// watchOS 9 or later. For these extensions, you can use the results from
84 /// ``DeviceCheck/DCAppAttestService/supported`` to indicate whether your
85 /// WatchKit extension bypasses attestation.
86 #[unsafe(method(isSupported))]
87 #[unsafe(method_family = none)]
88 pub unsafe fn isSupported(&self) -> bool;
89
90 #[cfg(feature = "block2")]
91 /// Creates a new cryptographic key for use with the App Attest service.
92 ///
93 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
94 /// > as shown on this page, or you can call it as an asynchronous method that has the
95 /// > following declaration:
96 /// >
97 /// > ```swift
98 /// > func generateKey() async throws -> String
99 /// > ```
100 /// > For example:
101 /// > ```swift
102 /// > let keyIdentifier = try await generateKey()
103 /// > ```
104 /// > For information about concurrency and asynchronous code in Swift, see
105 /// <doc
106 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
107 ///
108 /// Call this method to request the creation of a secure, unattested key pair on
109 /// a device for a specific user. On success, the method provides your app with
110 /// an identifier that represents the key pair stored in the Secure Enclave.
111 /// Because there’s no way to use or retrieve the key without the identifier,
112 /// you’ll want to either record it in your app or on your server right away. If
113 /// key generation fails, the closure provides a ``DeviceCheck/DCError-swift.struct`` that
114 /// indicates the reason for the failure.
115 ///
116 /// Create a unique key for each user account on a device. Otherwise it’s hard
117 /// to detect an attack that uses a single compromised device to serve multiple
118 /// remote users running a compromised version of your app. For more
119 /// information, see
120 /// <doc
121 /// :assessing-fraud-risk>.
122 ///
123 /// After you get the identifier, you call the
124 /// ``DeviceCheck/DCAppAttestService/attestKey:clientDataHash:completionHandler:``
125 /// method with the key identifier to ask Apple to attest to the validity of the
126 /// associated key. Later, you call the
127 /// ``DeviceCheck/DCAppAttestService/generateAssertion:clientDataHash:completionHandler:``
128 /// method with the key identifier to answer a challenge from your server, and
129 /// establish the legitimacy of this instance of your app.
130 ///
131 /// - Parameters:
132 /// - completionHandler: A closure that the method calls upon completion with
133 /// the following parameters:
134 /// - `keyId`: An identifier that you use to refer to the key. The framework securely
135 /// stores the key in the Secure Enclave.
136 /// - `error`: A ``DeviceCheck/DCError-swift.struct`` instance that indicates the
137 /// reason for failure, or `nil` on success.
138 #[unsafe(method(generateKeyWithCompletionHandler:))]
139 #[unsafe(method_family = none)]
140 pub unsafe fn generateKeyWithCompletionHandler(
141 &self,
142 completion_handler: &block2::Block<dyn Fn(*mut NSString, *mut NSError)>,
143 );
144
145 #[cfg(feature = "block2")]
146 /// Asks Apple to attest to the validity of a generated cryptographic key.
147 ///
148 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
149 /// > as shown on this page, or you can call it as an asynchronous method that has the
150 /// > following declaration:
151 /// >
152 /// > ```swift
153 /// > func attestKey(_ keyId: String, clientDataHash: Data) async throws -> Data
154 /// > ```
155 /// >
156 /// > For information about concurrency and asynchronous code in Swift, see
157 /// <doc
158 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
159 ///
160 /// This method asks Apple to attest to the validity of a key that you
161 /// previously generated with a call to the
162 /// ``DeviceCheck/DCAppAttestService/generateKeyWithCompletionHandler:`` method.
163 /// Provide the method with both the key identifier and a computed hash of a
164 /// data block that includes a one-time challenge from your server to prevent
165 /// replay attacks. For example, you can use CryptoKit to create a
166 /// <doc
167 /// ://com.apple.documentation/documentation/cryptokit/sha256> hash of
168 /// challenge data:
169 ///
170 /// ```swift
171 /// import CryptoKit let hash = Data(SHA256.hash(data: challenge)) // A
172 /// challenge from your server.
173 /// ```
174 /// The attest method calls its completion handler to return an attestation
175 /// object to you, which you must send to your server for verification. A
176 /// compromised version of your app could falsify the verification result, thus
177 /// circumventing App Attest.
178 ///
179 /// If you successfully verify the attestation object on your server, as
180 /// described in
181 /// <doc
182 /// :validating-apps-that-connect-to-your-server>, then you can
183 /// associate the key identifier with the user on the device for future
184 /// reference. You’ll need the identifier to generate assertions with calls to
185 /// ``DeviceCheck/DCAppAttestService/generateAssertion:clientDataHash:completionHandler:``.
186 /// If your server fails to verify the attestation object, discard the key
187 /// identifier.
188 ///
189 /// If the method’s completion handler returns the
190 /// ``DeviceCheck/DCError-swift.struct/serverUnavailable`` error — typically due to network
191 /// connectivity issues — it means that the framework failed to reach the App
192 /// Attest service to complete the attestation. In this case, retry attestation
193 /// again using the same key and client data hash later to avoid unnecessarily
194 /// generating new keys. Retrying with the same inputs helps to preserve the
195 /// risk metric for a given device.
196 ///
197 /// - Parameters:
198 /// - keyId: The identifier you received when generating a cryptographic key by
199 /// calling the
200 /// ``DeviceCheck/DCAppAttestService/generateKeyWithCompletionHandler:`` method.
201 /// - clientDataHash: A SHA256 hash of a unique, single-use data block that
202 /// embeds a challenge from your server. Should be at least 16 bytes in length.
203 /// - completionHandler: A closure that the method calls upon completion with
204 /// the following parameters:
205 /// - `attestationObject`: A statement from Apple about the validity of the key
206 /// associated with `keyId`. Send this to your server for processing.
207 /// - `error`: A ``DeviceCheck/DCError-swift.struct`` instance that indicates the reason for
208 /// failure, or `nil` on success.
209 #[unsafe(method(attestKey:clientDataHash:completionHandler:))]
210 #[unsafe(method_family = none)]
211 pub unsafe fn attestKey_clientDataHash_completionHandler(
212 &self,
213 key_id: &NSString,
214 client_data_hash: &NSData,
215 completion_handler: &block2::Block<dyn Fn(*mut NSData, *mut NSError)>,
216 );
217
218 #[cfg(feature = "block2")]
219 /// Creates a block of data that demonstrates the legitimacy of an instance of
220 /// your app running on a device.
221 ///
222 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
223 /// > as shown on this page, or you can call it as an asynchronous method that has the
224 /// > following declaration:
225 /// >
226 /// > ```swift
227 /// > func generateAssertion(_ keyId: String, clientDataHash: Data) async throws -> Data
228 /// > ```
229 /// >
230 /// > For information about concurrency and asynchronous code in Swift, see
231 /// <doc
232 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
233 ///
234 /// After generating a key with the
235 /// ``DeviceCheck/DCAppAttestService/generateKeyWithCompletionHandler:`` method
236 /// and validating it with the
237 /// ``DeviceCheck/DCAppAttestService/attestKey:clientDataHash:completionHandler:``
238 /// method, you can use the key at critical moments in your app’s life cycle —
239 /// like when a user tries to access premium content — to reaffirm the
240 /// legitimacy of a given instance of your app. Do this by using the
241 /// ``DeviceCheck/DCAppAttestService/generateAssertion:clientDataHash:completionHandler:``
242 /// method to sign server requests with your attested key.
243 ///
244 /// You provide the key identifier and a hash of the request that includes a
245 /// challenge from your server to prevent replay attacks, where an attacker
246 /// reuses captured network traffic to pose as someone else. The method returns
247 /// an assertion object in its completion handler that you send to your server
248 /// for verification, as described in
249 /// <doc
250 /// :establishing-your-app-s-integrity>.
251 ///
252 /// - Parameters:
253 /// - keyId: The identifier you received when generating a cryptographic key by
254 /// calling the
255 /// ``DeviceCheck/DCAppAttestService/generateKeyWithCompletionHandler:`` method.
256 /// - clientDataHash: A SHA256 hash of a unique, single-use data block that
257 /// represents the client data to be signed with the attested private key. Should be at least 16 bytes in length.
258 /// - completionHandler: A closure that the method calls upon completion with
259 /// the following parameters:
260 /// - `assertionObject`: A data structure that you send to your server for processing.
261 /// - `error` : A ``DeviceCheck/DCError-swift.struct`` instance that indicates the reason for failure, or `nil` on success.
262 #[unsafe(method(generateAssertion:clientDataHash:completionHandler:))]
263 #[unsafe(method_family = none)]
264 pub unsafe fn generateAssertion_clientDataHash_completionHandler(
265 &self,
266 key_id: &NSString,
267 client_data_hash: &NSData,
268 completion_handler: &block2::Block<dyn Fn(*mut NSData, *mut NSError)>,
269 );
270 );
271}
272
273/// Methods declared on superclass `NSObject`.
274impl DCAppAttestService {
275 extern_methods!(
276 #[unsafe(method(init))]
277 #[unsafe(method_family = init)]
278 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
279
280 #[unsafe(method(new))]
281 #[unsafe(method_family = new)]
282 pub unsafe fn new() -> Retained<Self>;
283 );
284}