Play Integrity API

Native Play Integrity API.

Summary

Enumerations
IntegrityErrorCode{ INTEGRITY_NO_ERROR = 0, INTEGRITY_API_NOT_AVAILABLE = -1, INTEGRITY_PLAY_STORE_NOT_FOUND = -2, INTEGRITY_NETWORK_ERROR = -3, INTEGRITY_PLAY_STORE_ACCOUNT_NOT_FOUND = -4, INTEGRITY_APP_NOT_INSTALLED = -5, INTEGRITY_PLAY_SERVICES_NOT_FOUND = -6, INTEGRITY_APP_UID_MISMATCH = -7, INTEGRITY_TOO_MANY_REQUESTS = -8, INTEGRITY_CANNOT_BIND_TO_SERVICE = -9, INTEGRITY_NONCE_TOO_SHORT = -10, INTEGRITY_NONCE_TOO_LONG = -11, INTEGRITY_GOOGLE_SERVER_UNAVAILABLE = -12, INTEGRITY_NONCE_IS_NOT_BASE64 = -13, INTEGRITY_PLAY_STORE_VERSION_OUTDATED = -14, INTEGRITY_PLAY_SERVICES_VERSION_OUTDATED = -15, INTEGRITY_INTERNAL_ERROR = -100, INTEGRITY_INITIALIZATION_NEEDED = -101, INTEGRITY_INITIALIZATION_FAILED = -102, INTEGRITY_INVALID_ARGUMENT = -103 }	enum Errors that can be encountered while using the integrity API.
`IntegrityResponseStatus{ INTEGRITY_RESPONSE_UNKNOWN = 0, INTEGRITY_RESPONSE_PENDING = 1, INTEGRITY_RESPONSE_COMPLETED = 2 }`	enum Status returned when requesting integrity tokens.

Enumerations

IntegrityErrorCode{
  INTEGRITY_NO_ERROR = 0,
  INTEGRITY_API_NOT_AVAILABLE = -1,
  INTEGRITY_PLAY_STORE_NOT_FOUND = -2,
  INTEGRITY_NETWORK_ERROR = -3,
  INTEGRITY_PLAY_STORE_ACCOUNT_NOT_FOUND = -4,
  INTEGRITY_APP_NOT_INSTALLED = -5,
  INTEGRITY_PLAY_SERVICES_NOT_FOUND = -6,
  INTEGRITY_APP_UID_MISMATCH = -7,
  INTEGRITY_TOO_MANY_REQUESTS = -8,
  INTEGRITY_CANNOT_BIND_TO_SERVICE = -9,
  INTEGRITY_NONCE_TOO_SHORT = -10,
  INTEGRITY_NONCE_TOO_LONG = -11,
  INTEGRITY_GOOGLE_SERVER_UNAVAILABLE = -12,
  INTEGRITY_NONCE_IS_NOT_BASE64 = -13,
  INTEGRITY_PLAY_STORE_VERSION_OUTDATED = -14,
  INTEGRITY_PLAY_SERVICES_VERSION_OUTDATED = -15,
  INTEGRITY_INTERNAL_ERROR = -100,
  INTEGRITY_INITIALIZATION_NEEDED = -101,
  INTEGRITY_INITIALIZATION_FAILED = -102,
  INTEGRITY_INVALID_ARGUMENT = -103
}

enum

Errors that can be encountered while using the integrity API.

IntegrityResponseStatus{
  INTEGRITY_RESPONSE_UNKNOWN = 0,
  INTEGRITY_RESPONSE_PENDING = 1,
  INTEGRITY_RESPONSE_COMPLETED = 2
}

enum

Status returned when requesting integrity tokens.

Typedefs
`IntegrityTokenRequest`	typedef `struct IntegrityTokenRequest_` An opaque struct used to provide information about an integrity token request.
`IntegrityTokenResponse`	typedef `struct IntegrityTokenResponse_` An opaque struct used to access information about an integrity token response.

Functions
`IntegrityManager_destroy()`	`void` Frees up memory allocated for the Integrity API.
`IntegrityManager_init(JavaVM *jvm, jobject android_context)`	`IntegrityErrorCode` Initialize the Play Integrity API, making the other functions available to call.
`IntegrityManager_requestIntegrityToken(IntegrityTokenRequest request, IntegrityTokenResponse *out_response)`	`IntegrityErrorCode` Starts an asynchronous operation to obtain a Play Integrity API token.
`IntegrityTokenRequest_create(IntegrityTokenRequest **out_request)`	`IntegrityErrorCode` Creates a new IntegrityTokenRequest opaque struct.
`IntegrityTokenRequest_destroy(IntegrityTokenRequest *request)`	`void` Releases the specified IntegrityTokenRequest and any references it holds.
`IntegrityTokenRequest_setCloudProjectNumber(IntegrityTokenRequest *request, int64_t cloudProjectNumber)`	`IntegrityErrorCode` Sets the cloud project number to link to the integrity token.
`IntegrityTokenRequest_setNonce(IntegrityTokenRequest request, const char nonce)`	`IntegrityErrorCode` Sets the nonce in an IntegrityTokenRequest with a given string.
`IntegrityTokenResponse_destroy(IntegrityTokenResponse *response)`	`void` Releases the specified IntegrityTokenResponse and any references it holds.
`IntegrityTokenResponse_getStatus(IntegrityTokenResponse response, IntegrityResponseStatus out_status)`	`IntegrityErrorCode` Gets the status of an ongoing IntegrityManager_requestIntegrityToken() asynchronous operation.
`IntegrityTokenResponse_getToken(IntegrityTokenResponse *response)`	`const char *` Gets the token retrieved by a successful IntegrityManager_requestIntegrityToken() asynchronous operation, returns null pointer otherwise.

Enumerations

IntegrityErrorCode

 IntegrityErrorCode

Errors that can be encountered while using the integrity API.

Properties
`INTEGRITY_API_NOT_AVAILABLE`	Integrity API is not available. Integrity API is not enabled, or the Play Store version might be old. Recommended actions: Make sure that Integrity API is enabled in Google Play Console. Ask the user to update Play Store.
`INTEGRITY_APP_NOT_INSTALLED`	The calling app is not installed. Something is wrong (possibly an attack). Non-actionable.
`INTEGRITY_APP_UID_MISMATCH`	The calling app UID (user id) does not match the one from Package Manager. Something is wrong (possibly an attack). Non-actionable.
`INTEGRITY_CANNOT_BIND_TO_SERVICE`	Binding to the service in the Play Store has failed. This can be due to having an old Play Store version installed on the device. Ask the user to update Play Store.
`INTEGRITY_GOOGLE_SERVER_UNAVAILABLE`	Unknown internal Google server error. Retry with an exponential backoff. Consider filing a bug if fails consistently.
`INTEGRITY_INITIALIZATION_FAILED`	There was an error initializing the Integrity API. Retry with an exponential backoff. Consider filing a bug if fails consistently.
`INTEGRITY_INITIALIZATION_NEEDED`	IntegrityManager is not initialized. Call IntegrityManager_init() first.
`INTEGRITY_INTERNAL_ERROR`	Unknown internal error. Retry with an exponential backoff. Consider filing a bug if fails consistently.
`INTEGRITY_INVALID_ARGUMENT`	Invalid argument passed to the Integrity API. Retry with correct argument.
`INTEGRITY_NETWORK_ERROR`	No available network is found. Ask the user to check for a connection.
`INTEGRITY_NONCE_IS_NOT_BASE64`	Nonce is not encoded as a Base64 web-safe no-wrap string. Retry with correct nonce format.
`INTEGRITY_NONCE_TOO_LONG`	Nonce length is too long. The nonce must be less than 500 bytes before Base64 encoding. Retry with a shorter nonce.
`INTEGRITY_NONCE_TOO_SHORT`	Nonce length is too short. The nonce must be a minimum of 16 bytes (before Base64 encoding) to allow for a better security. Retry with a longer nonce.
`INTEGRITY_NO_ERROR`	No error has occurred.
`INTEGRITY_PLAY_SERVICES_NOT_FOUND`	Play Services is not available or version is too old. Ask the user to Install or Update Play Services.
`INTEGRITY_PLAY_SERVICES_VERSION_OUTDATED`	Play Services needs to be updated. Ask the user to update Google Play Services.
`INTEGRITY_PLAY_STORE_ACCOUNT_NOT_FOUND`	No Play Store account is found on device. Note that the Play Integrity API now supports unauthenticated requests. This error code is used only for older Play Store versions that lack support. Ask the user to authenticate in Play Store.
`INTEGRITY_PLAY_STORE_NOT_FOUND`	No Play Store app is found on device or not official version is installed. Ask the user to install an official and recent version of Play Store.
`INTEGRITY_PLAY_STORE_VERSION_OUTDATED`	The Play Store needs to be updated. Ask the user to update the Google Play Store.
`INTEGRITY_TOO_MANY_REQUESTS`	The calling app is making too many requests to the API and hence is throttled. Retry with an exponential backoff.

IntegrityResponseStatus

 IntegrityResponseStatus

Status returned when requesting integrity tokens.

Properties
`INTEGRITY_RESPONSE_COMPLETED`	IntegrityManager_requestIntegrityToken() asynchronous operation has finished.
`INTEGRITY_RESPONSE_PENDING`	Waiting for IntegrityManager_requestIntegrityToken() asynchronous operation to finish.
`INTEGRITY_RESPONSE_UNKNOWN`	The response status is unknown.

Typedefs

IntegrityTokenRequest

struct IntegrityTokenRequest_ IntegrityTokenRequest

An opaque struct used to provide information about an integrity token request.

IntegrityTokenResponse

struct IntegrityTokenResponse_ IntegrityTokenResponse

An opaque struct used to access information about an integrity token response.

Functions

IntegrityManager_destroy

void IntegrityManager_destroy()

Frees up memory allocated for the Integrity API.

Does nothing if IntegrityManager_init() hasn't been called.

IntegrityManager_init

IntegrityErrorCode IntegrityManager_init(
  JavaVM *jvm,
  jobject android_context
)

Initialize the Play Integrity API, making the other functions available to call.

In case of failure the Play Integrity API is unavailable, and there will be an error in logcat. The most common reason for failure is that the PlayCore AAR is missing or some of its classes/methods weren't retained by ProGuard. See also:IntegrityManager_destroy

Details

Parameters

`jvm`	The app's single JavaVM, for example from ANativeActivity's "vm" field.
`android_context`	An Android Context, for example from ANativeActivity's "clazz" field.

Returns

INTEGRITY_NO_ERROR if initialization succeeded, or an error if failed.

IntegrityManager_requestIntegrityToken

IntegrityErrorCode IntegrityManager_requestIntegrityToken(
  IntegrityTokenRequest *request,
  IntegrityTokenResponse **out_response
)

Starts an asynchronous operation to obtain a Play Integrity API token.

For an ongoing asynchronous operation, use IntegrityTokenResponse_getStatus() to poll for the status of the IntegrityTokenResponse. When the status reaches INTEGRITY_RESPONSE_COMPLETED with INTEGRITY_NO_ERROR, use IntegrityTokenResponse_getToken() to acquire the resulting token.

See also: IntegrityTokenResponse_destroy

Details

Parameters

`request`	The request containing the nonce.
`out_response`	An out parameter for receiving the result.

Returns

INTEGRITY_NO_ERROR if the request started successfully, corresponding error if failed.

IntegrityTokenRequest_create

IntegrityErrorCode IntegrityTokenRequest_create(
  IntegrityTokenRequest **out_request
)

Creates a new IntegrityTokenRequest opaque struct.

See also: IntegrityTokenRequest_destroy

Details

Parameters

out_request

An out parameter for receiving the result.

Returns

An IntegrityErrorCode, which if not INTEGRITY_NO_ERROR indicates that the out parameter shouldn't be used.

IntegrityTokenRequest_destroy

void IntegrityTokenRequest_destroy(
  IntegrityTokenRequest *request
)

Releases the specified IntegrityTokenRequest and any references it holds.

Details

Parameters

request

The request to free.

IntegrityTokenRequest_setCloudProjectNumber

IntegrityErrorCode IntegrityTokenRequest_setCloudProjectNumber(
  IntegrityTokenRequest *request,
  int64_t cloudProjectNumber
)

Sets the cloud project number to link to the integrity token.

This is an optional field and is meant to be used only for apps not available on Google Play or by SDKs that include the Play Integrity API.

Cloud project number is an automatically generated unique identifier for your Google Cloud project. It can be found in Project info in your Google Cloud Console for the cloud project where Play Integrity API is enabled.

Details

Parameters

`request`	The IntegrityTokenRequest to set cloudProjectNumber.
`cloudProjectNumber`	The cloudProjectNumber for the request.

Returns

An IntegrityErrorCode, which if not INTEGRITY_NO_ERROR indicates that this operation has failed.

IntegrityTokenRequest_setNonce

IntegrityErrorCode IntegrityTokenRequest_setNonce(
  IntegrityTokenRequest *request,
  const char *nonce
)

Sets the nonce in an IntegrityTokenRequest with a given string.

A nonce is a unique token which is ideally bound to the context (e.g. hash of the user id and timestamp). The provided nonce will be a part of the signed response token, which will allow you to compare it to the original one and hence prevent replay attacks.

Nonces should always be generated in a secure server environment. Do not generate a nonce from within the client app.

It must be Base64 encoded in web-safe no-wrap form.

Details

Parameters

`request`	The IntegrityTokenRequest for which to set token.
`nonce`	The nonce for the request.

Returns

An IntegrityErrorCode, which if not INTEGRITY_NO_ERROR indicates that this operation has failed.

IntegrityTokenResponse_destroy

void IntegrityTokenResponse_destroy(
  IntegrityTokenResponse *response
)

Releases the specified IntegrityTokenResponse and any references it holds.

Details

Parameters

response

The response to free.

IntegrityTokenResponse_getStatus

IntegrityErrorCode IntegrityTokenResponse_getStatus(
  IntegrityTokenResponse *response,
  IntegrityResponseStatus *out_status
)

Gets the status of an ongoing IntegrityManager_requestIntegrityToken() asynchronous operation.

This function can be used to poll for the completion of a call to IntegrityManager_requestIntegrityToken(). This function does not make any JNI calls and can be called every frame.

Details

Parameters

`response`	The IntegrityTokenResponse for which to get status.
`out_status`	An out parameter for receiving the IntegrityResponseStatus.

Returns

An IntegrityErrorCode indicating the error associated with the given IntegrityTokenResponse.

IntegrityTokenResponse_getToken

const char * IntegrityTokenResponse_getToken(
  IntegrityTokenResponse *response
)

Gets the token retrieved by a successful IntegrityManager_requestIntegrityToken() asynchronous operation, returns null pointer otherwise.

The JSON payload is signed and encrypted as a nested JWT, that is JWE of JWS.

JWE uses A256KW as a key wrapping algorithm and A256GCM as a content encryption algorithm. JWS uses ES256 as a signing algorithm.

All decryption and verification should be done within a secure server environment. Do not decrypt or verify the received token from within the client app. In particular, never expose any decryption keys to the client app.

The string returned here is owned by the API, and the pointer will be valid until the corresponding IntegrityTokenResponse is freed by calling IntegrityTokenResponse_destroy().

Details

Parameters

response

The IntegrityTokenResponse specifying the asynchronous operation.

Returns

A token which contains the response for the integrity related enquiries.