+ SafetyNet provides access to Google services that help you assess the health and safety of an + Android device. The wide variety of Android devices and configurations can make it difficult to + know if your app will behave as you expect on all available devices. The SafetyNet API helps you + determine if your app will function properly on a device by analyzing its compatibility with the + Android platform specifications. +
+ ++ Check if your app is running on a device that matches a device model that has passed Android + compatibility testing. This analysis can help you determine if your app will work as expected on + the device where it is installed. The service evaluates both software and hardware + characteristics of the device, and may use hardware roots of trust, when available. +
+ ++ Use of SafetyNet is governed by specific terms of service, in addition to the Google APIs Terms of Service. + Before using this API, review the + Additional Terms of Service. +
+ ++ SafetyNet is part of the Google Play services platform. To get started, follow the instructions + for Setting + up Google Play services. +
+ ++ Learn how to use SafetyNet in your app by reading the Getting Started instructions. For more + details on the API, see the + SafetyNet reference documentation. +
+ ++ SafetyNet provides services for analyzing the configuration of a particular device, to make sure + that apps function properly on a particular device and that users have a great experience. +
+ ++ The service provides an API your app can use to analyze the device where it is installed. The API + uses software and hardware information on the device where your app is installed to create a + profile of that device. The service then attempts to match it to a list of device models that + have passed Android compatibility testing. This check can help you decide if the device is + configured in a way that is consistent with the Android platform specifications and has the + capabilities to run your app. +
+ ++ This document shows you how to use SafetyNet for analyzing a device and help you determine if + your app will function as expected on that device. +
+ ++ By accessing or using the SafetyNet APIs, you agree to the Google APIs Terms of Service, and to these Additional + Terms. Please read and understand all applicable terms and policies before accessing the APIs. +
+ ++ The SafetyNet API is part of Google Play services. To connect to the API, you need to create an + instance of the Google Play services API client. For details about using the client in your app, + see Accessing Google + APIs. Once you have established a connection to Google Play services, you can use the Google + API client classes to connect to the SafetyNet API. +
+ ++ To connect to the API, in your activity's onCreate() + method, create an instance of Google API Client using + {@code GoogleApiClient.Builder}. Use the builder to add the SafetyNet API, as shown in the + following code example: +
+ +
+protected synchronized void buildGoogleApiClient() {
+ mGoogleApiClient = new GoogleApiClient.Builder(this)
+ .addApi(SafetyNet.API)
+ .addConnectionCallbacks(myMainActivity.this)
+ .build();
+}
+
+
++ Note: You can only call these methods after your app has established a connection to + Google Play services by receiving the + {@code onConnected()} callback. For details about listening for a completed client connection, + see Accessing Google APIs. +
+ ++ A SafetyNet compatibility check allows your app to check if the device where it is running + matches the profile of a device that has passed Android compatibility testing. The compatibility + check creates a device profile by gathering information about the device hardware and software + characteristics, including the platform build. +
+ ++ Using the API to perform a check requires a few implementation steps in your app. Once you have + established a connection to Google Play services and requested the SafetyNet API from the Google + API client, your app can then perform the following steps to use the service: +
+ ++ For more information about Android compatibility testing, see + Android Compatibility and the + Compatibility Testing Suite (CTS). +
+ ++ SafetyNet checks use network resources, and so the speed of responses to requests can vary, + depending on a device's network connection status. The code described in this section should be + executed outside of your app's main execution thread, to avoid pauses and unresponsiveness in + your app user interface. For more information about using separate execution threads, see + Sending Operations + to Multiple Threads. +
+ ++ The SafetyNet API uses security techniques to help you verify the integrity of the communications + between your app and the service. When you request a compatibility check, you must provide a + single use token in the form of a number used once, or nonce, as part of your request. A + nonce is a random token generated in a cryptographically secure manner. +
+ ++ You can obtain a nonce by generating one within your app each time you make a compatibility check + request. As a more secure option, you can obtain a nonce from your own server, using a secure + connection. +
+ ++ A nonce used with a SafetyNet request should be at least 16 bytes in length. After you make a + check request, the response from the SafetyNet service includes your nonce, so you can verify it + against the one you sent. As the name indicates, you should only use a nonce value once, for a + single check request. Use a different nonce for any subsequent check requests. For tips on using + cryptography functions, see Security Tips. +
+ ++ After you have established a connection to Google Play services and created a nonce, you are + ready to make a compatibility check request. Since the response to your request may not be + immediate, you set up a callback listener to catch the response from the service, as shown in the + following code example: +
+ +
+byte[] nonce = getRequestNonce(); // Should be at least 16 bytes in length.
+SafetyNet.SafetyNetApi.attest(mGoogleApiClient, nonce)
+ .setResultCallback(new ResultCallback<SafetyNetApi.AttestationResult>() {
+
+ @Override
+ public void onResult(SafetyNetApi.AttestationResult result) {
+ Status status = result.getStatus();
+ if (status.isSuccess()) {
+ // Indicates communication with the service was successful.
+ // result.getJwsResult() contains the result data
+ } else {
+ // An error occurred while communicating with the service
+ }
+ }
+});
+
+
++ The + {@code isSuccess()} + method indicates whether or not communication with the service was successful, but does not + indicate if the device has passed the compatibility check. The next section discusses how to read + the check result and verify its integrity. +
+ ++ When your app communicates with SafetyNet, the service provides a response containing the result + and additional information to help you verify the integrity of the message. The result is + provided as a + {@code AttestationResult} + object. Use the +{@code getJwsResult()} method of this object to obtain the data of the request. The response is + formatted as a + JSON Web Signature (JWS), the following JWS excerpt shows the format of the payload data: +
+ +
+{
+"nonce": "R2Rra24fVm5xa2Mg",
+"timestampMs": 9860437986543,
+"apkPackageName": "com.package.name.of.requesting.app",
+"apkCertificateDigestSha256": ["base64 encoded, SHA-256 hash of the
+certificate used to sign requesting app"],
+"apkDigestSha256": "base64 encoded, SHA-256 hash of the app's APK",
+"ctsProfileMatch": true,
+}
+
+
++ If the value of {@code ctsProfileMatch} is {@code true}, this indicates that the device + profile matches a device that has passed Android compatibility testing. If the output of the + +{@code getJwsResult()} method is null or contains an {@code error:} field, then communication + with the service failed and should be retried. You should use an exponential backoff technique for + retries, to avoid flooding the service with additional requests. +
+ ++ You should take steps to make sure the response received by your app actually came from the + SafetyNet service and matches the request data you provided. Follow these steps to verify the + origin of the JWS message: +
+ ++ After completing this validation, you should also check the data of the JWS message to make sure + it matches your original request, including the nonce, timestamp, package name, and the SHA-256 + hashes. You can perform these validation steps within your app, or as a more secure option, send + the entire JWS response to your own server for verification, via a secure connection. +
+ ++ Google provides an Android Device Verification API for validating the output of the SafetyNet + compatibility check. This API performs a validation check on the JWS message returned from the + SafetyNet service. +
+ ++ To enable access to the Android Device Verification API: +
+ ++ After enabling this API for your project, you can call the verification service from your app or + server. You need the contents of the JWS message from the SafetyNet API and your API key to call + the verification API and get a result. +
+ ++ To use the Android Device Verification API: +
+ +
+{ "signedAttestation": "<output of getJwsResult()>" }
+
+ +https://www.googleapis.com/androidcheck/v1/attestations/verify?key=<your API key> ++
+{ “isValidSignature”: true }
+
+ + Important: This use of the Android Device Verification API only validates that the + provided JWS message was received from the SafetyNet service. It does not verify that the + payload data matches your original compatibility check request. +
\ No newline at end of file