Installation
For SDK method references, see Integration Hardening.
This is an advanced option that enables a method in the SDK to sign arbitrary messages using an app installation specific key. A key pair is generated automatically when the SDK is first initialized. The public key is transmitted to Approov servers and may be included in Approov tokens in the ipk claim. The private key, however, never leaves the device itself. The keys will be held in secure hardware (TEE/Secure Enclave) to prevent the key material being exfiltrated from the device. During Approov attestations the device must prove it has possession of the key by signing one-time (nonce) data provided by the Approov servers. Installation keys are always asymmetric key pairs generated using Elliptic Curve Cryptography.
The feature ensures strict message integrity between the client app and the backend API. Message integrity is also assured by Managing Dynamic Pinning, which we strongly recommend that you implement (all of our frontend integration quickstarts do this). We provide installation message signing as an advanced option for certain situations where an additional level of integrity assurance is required.
Installation message signing is only available in 3.4.0 and later SDKs.
As well as installation specific message signing, Approov also offers Account Message Signing where requests are signed using an account specific key. Both methods can be employed together, but we would advise the use of this installation message signing before employing the account message signing option.
Key Attestation
On Android the generated key pairs are subject to a key attestation process. This provides confidence that the keys have indeed been generated on a real Android device and are being actively protected in a TEE.
All SDKs from 3.4.0 will generate key pairs automatically. However, you may have apps running with older Approov SDKs in your account. If you enable the option flag require-install-key then this ensures that all app installations have keys, or else they will be rejected with failed-requirement.
By default there is no requirement for the key pair that is generated to be attested. It is possible to opt into this using the option flag require-android-tee. If this is enabled then all key pairs on Android must be attested to be secure in a Trusted Execution Environment (TEE) or StrongBox. Any device not able to do this will be rejected with failed-requirement. Note that Android 6.0 devices do not have this capability so will not be able to receive valid Approov tokens.
Furthermore, by default the key attestation will accept keys attested by various TEE implementations. The root certificate in the chain provided by the attestation shows the root authority. If the option flag require-certified-key-attest if enabled then only root certificates from Google and certain other trusted hardware manufacturers will be accepted, and other attestations will be rejected with failed-requirement.
Key pairs on iOS are not subject to key attestation because this feature is not provided directly in iOS. The keys will be held securely in the key chain, but this is not subject to the same level of rigourous verification as is possible in Android. However, you can enable AppAttest which provides some additional security guarantees regarding the attestation of key material on a real iOS device.
Enabling Installation Message Signing
Checking of installation message signing on the backend is signalled by including the installation's public key in Approov tokens in the ipk claim. The claim is base64 DER encoded ASN.1 public key information. If the public key is included then this is used to indicate to the backend that it should expect a valid installation message signature. The feature can be enabled as follows:
approov policy -setInstallPubKey on
An admin role and confirmation is required to make the policy change:
WARNING: updating the subject policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
installation public key policy was set successfully
Simply use off as a parameter to disable this again if required.
The current policy can always be retrieved as follows:
approov policy -getInstallPubKey
Implementing Installation Message Signing
The Mobile App Quickstarts support installation message signing as a configuration option. The configuration options also specify the set of headers that should be included in the signatures. All headers that are intended to reach the backend server and influence its behaviour should be included. The request HTTP verb, URL and body are always included.
When enabled, the quickstart integration concatenates the relevant parts of a request into a single string. This is then passed to the installation signing method in the SDK to obtain the signature. This signature is then itself added to the request as an additional header. This is provided in addition to the Approov token header, which is included in the message integrity calculation. Moreover, you should always include the Approov token itself as part of the string submitted for signing as this prevents replay attacks (since the Approov token has a short expiration time).
Various of the Backend API Quickstarts also support installation message signing checking. The backend API will first check the validity of the Approov token in the normal way. If the installation public key ipk claim is present in the token then it will also check the installation message signing integrity. It is able to gather the components of the request and build the same single string as the client and verify the expected signature against the public key provided. A failure indicates that the request has been tampered with in some way during transit or the originator of the message did not have access to private key corresponding to the public key provided.
It is not necessary to enforce signature checking on all API endpoints. You may wish to only apply it on particularly security sensitive ones. Of course, there must be consistency between the app and the backend API in these choices.