Security & Policy
Overview
The Approov Command Line Interface (CLI) is used for administering the operation of your Approov service. Builds of the tool are available for Linux, MacOS and Windows. Follow the Approov CLI Tool Installation instructions if you do not have it installed.
AppAttest Command
approov appattest [option]...
info
Note that appattest commands (apart from -get) requires the use of an admin or delegate role.
| Option | Description |
-addAuthKey <auth-file> | Adds a DeviceCheck key to your account and enables the use of Apple AppAttest fraud lookup in your account. The key is downloaded from the Apple developer portal and should be of the form AuthKey_ID.p8, where the ID is the identifier for your particular key. The key must have been granted DeviceCheck privileges. |
-addTeamID <ID> | This option enables the use of AppAttest for your iOS apps. The ID is the Apple team identifier for your Apps. |
-get | Gets and shows the current state of the AppAttest configuration. |
-remove | Removes use of AppAttest in your account. |
-removeAuthKey | Disables use of fraud lookups for AppAttest. |
-setAssertionPeriod <value> | Sets the assertion period for AppAttest to the number of hours specified in value. This means that if an app instance is running for more than the specified number of hours, then a subsequent Approov fetch will require a new AppAttest assertion to be performed. If always is specified then assertions are performed on all Approov fetches, and this is the default. Note that an assertion is always performed on a new launch of the app. |
-setMaxRisk <value> | Sets the maximum acceptable risk for a fraud lookup to the value specified. This is only relevant if -addAuthKey has been used to allow fraud lookups. The risk metric is a heuristic supplied by Apple that determines the level of attested keys for the app associated with a particular device, and a high value may indicate fraud. |
-setRateLimit <value> | Sets the maximum number of attestations to be performed per hour for the account. This may be used to limit the number of requests to Apple when initially onboarding a large user base. If the default value of unlimited is used then all new app installs will perform an AppAttest. |
Custom JWT Command
approov customjwt [option]...
| Option | Description |
-clearKeySetKID | Removes any keyset KID associated with the custom JWT, so that signing returns to using the HS256 algorithm with the account secret. An admin role is required to perform this operation. |
-get | Gets the current state of the custom JWT feature. |
-keySetKID <kid> | Selects a particular keyset kid to be used for signing custom JWTs. This causes the kid claim to be added to the token header and the appropriate signing algorithm used. An admin role is required to perform this operation. |
-setDisabled | Disables the custom JWT feature. Subsequent attempts to fetch a custom JWT from the app will result in a REJECTED / rejected error. An admin role is required to perform this operation. |
-setEnabled | Enables the use of the custom JWT feature. By default the tokens will be signed using the HS256 algorithm using the account secret. An admin role is required to perform this operation. |
Installation Attributes Command
approov installattrs [option]...
| Option | Description |
-add <algorithm> | Adds a new installation attributes token signing key suitable for use with the specified algorithm. Possible options are HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 or ES512. A new random key is generated by the Approov server. A key name must be specified with the -kid option. For some key types the -keyLength option may be used to override the default key length. |
-genExample <file> | Generates an example token with the payload as given in file, which must be a validly formatted JSON file. Note that the payload must contain a did claim with a 128-bit base64 encoded device ID. A key name must be specified with the -kid option. |
-getJWKS <pathname> | Gets a JSON Web Key Set (JWKS) format file, providing all of the private keys for signing installation attributes tokens. An admin role is required. |
-getPEM <pathname> | Gets a PEM encoded form of the private key specified by the |
-import <pathname> | Imports a private key for signing installation attributes tokens from the given pathname. This file must be in JSON Web Key (JWK) format. Note that the alg and use claims must be present and must be one of those supported by Approov. The key is imported with the name specified in the kid claim (which must not already be present). |
-keyLength <bits> | May be used in conjunction with a -add option to override the default key length for certain key types. For RSA types (RS256, RS384, RS512, PS256, PS384, PS512) a default key length of 2048 bits is used, but may be overridden to 1024 or 4096 bits. For symmetric key types (HS256, HS384, HS512) the default is 256 bits, but may be overridden to 128 bits or 512 bits. |
-kid <name> | Specifies a key identifier to be used with a -add, -getPEM, -remove or -genExample option. |
-list | Lists all of the keys that might be used to sign installation attributes tokens. |
-remove | Removes the key that must be specified with the -kid option. This option requires an admin role. |
-verify <token> | Verifies the given token that has been generated as an installation attributes token. This verifies the format of the token and checks if it has been correctly signed. Note that no check is made of whether the token has expired. |
Keyset Command
approov keyset [option]...
| Option | Description |
-add <algorithm> | Adds a new key to the keyset suitable for use with the specified algorithm. Possible options are HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384 and ES512 for JWS signing. The algorithm A256GCMKW may be used for JWE encryption. A new random key is generated by the Approov server. For asymmetric key types it is never possible to obtain the private key, only the public key for verification. By default the key ID is generated automatically in a numeric sequence but this may be overridden with the -kid option to specify a particular named ID. For some key types the -keyLength option may be used to override the default key length. |
-getJWKS <pathname> | Gets a JSON Web Key Set (JWKS) format file, providing all of the public keys in the keyset. Note that if the returned set contains symmetric keys then it must be carefully secured as the associated entries can be used to sign new tokens as well as verify them. An admin role is required. |
-getJWKSURI | Gets the current status of whether the JWKS URI is enabled or not. If it is then a URL on which a JSON Web Key Set (JWKS) can be obtained is provided. This only ever provides public keys. |
-getPEM <pathname> | Gets a PEM encoded form of the public key specified by the -kid option. It is in PKIX ASN.1 DER format. The encoded public key is a SubjectPublicKeyInfo structure, as defined in RFC5280, section 4.1. It is only possible to obtain a PEM for RSA and ECDSA key types. The public key may be used to verify the authenticity of Approov tokens generated using the specified key. |
-import <pathname> | Imports a private key into the keyset from the given pathname. This file must be in JSON Web Key (JWK) format. Note that the alg and use claims must be present and must be one of those supported by Approov. The key is imported with the name specified in the kid claim (which must not already be present). An admin role is required. |
-keyLength <bits> | May be used in conjunction with a -add option to override the default key length for certain key types. For RSA types (RS256, RS384, RS512, PS256, PS384, PS512) a default key length of 2048 bits is used, but may be overridden to 1024 or 4096 bits. For symmetric key types (HS256, HS384, HS512, A256GCMKW) the default is 256 bits, but may be overridden to 128 bits or 512 bits. |
-kid <name> | Specifies a key identifier to be used with a -add, -getPEM or -remove option. |
-list | Lists all of the keys in the keyset, their algorithm and also any API domains by which they are used. |
-remove | Removes the key from the keyset that must be specified with the -kid option. The removal is only possible if the key is not currently being used by an API domain. This option requires an admin role. |
-setJWKSURI <policy> | Sets the JWKS enablement policy to either being on or off. If the policy is enabled then a URL on which a JSON Web Key Set (JWKS) can be obtained is provided. This only ever provides public keys. This requires an admin role. |
-type <type> | An optional identifier for the keyset used to sign the Approov token. Use pass or fail to specify the attestation outcome. If omitted, the pass keyset is returned by default.
This parameter is used in conjunction with the -getJWKS or -getPEM commands. |
Play Integrity Command
approov playintegrity [option]...
info
Note that playintegrity commands (apart from -get) requires the use of an admin or delegate role.
| Option | Description |
-addCredentials <file> | Enables Play Integrity checking by adding the Google access credentials file. This should be a Google service account JSON file which provides access to the Google Play Integrity API. Once the credentials have been set, it is not possible to retrieve them from Approov again. The -get option will only provide the key ID. |
-clearProjectNumber | Clears any Google project number previously set using -addProjectNumber. If no project number is specified then only apps released in the Google Play store can receive Play Integrity tokens. |
-clearRequireAppIntegrity | Clears any required app integrity verdicts previously set with -setRequireAppIntegrity. If this option is used then the app is never rejected on the basis of the app integrity. |
-clearRequireAppLicensing | Clears any required app licensing verdicts that have been previously set with -setRequireAppLicensing. If this option is used then the app is never rejected on the basis of app licensing. |
-clearRequireDeviceIntegrity | Clears any required device integrity verdicts that have been previously set with -setRequireDeviceIntegrity. If this option is used then the app is never rejected on the basis of the device integrity. |
-get | Shows the current setting of Play Integrity, including any Key ID used for access and the current settings of required integrity verdicts. |
-remove | Disables Play Integrity so that integrity tokens are not requested and no rejections will be made on the basis of any prior integrity results. |
-setCloudProjectNumber <value> | Sets the Google Cloud Project number in the value order to use Play Integrity on apps not yet distributed through the Google Play store or for apps that will be distributed outside of the Google Play. |
-setRateLimit <value> | Sets the rate limit value in terms of the maximum new Play Integrity attestations that will be requested per hour. By default the value will be unlimited, and this value may be set again any time. This allows you to conform to the usage tier associated with your app. These are expressed in terms of daily quotas, so you should divide by 24 to obtain an hourly rate limit. If the quota is exceeded then no request for a Play Integrity is made but the app is still able to run, with a request delayed for the Play Integrity token until the next time the app is launched. |
-setRecheckPeriod <value> | By default, a Play Integrity check is performed the first time an app is launched after being installed and this is not repeated. This corresponds to the default value of never, which may be reinstated at any point. Another value in hours may be set which causes the Play Integrity attestation to be repeated the next time the app is launched and the previous attestation was more than the given number of hours ago. Note that this additional Play Integrity attestation will impose latency and will have an impact on the usage of your app's Play Integrity use quota. |
-setRequireAppCert <setting> | Sets whether the certificateSha256Digest provided from a Play Integrity attestation should be compared against those added with approov appsigncert. The value of setting may be on or off. If turned on then the attestation is rejected if some appsigncert certificates have been added and none matched that provided from the attestation, as this would indicate the request did not appear to come from the expected app. |
-setRequireAppIntegrity <verdicts> | Sets the list of | separated verdicts that are acceptable as an application integrity verdict. The possible values are provided here. |
-setRequireAppLicensing <verdicts> | Sets the list of | separated verdicts that are acceptable as an app licensing integrity verdict. The possible values are provided here in terms of the appLicensingVerdict field. |
-setRequireDeviceIntegrity <verdicts> | Sets the list of | separated verdicts that are acceptable as a device integrity verdict. The possible values are provided here. Note that you can opt-in in the Google Play console to potentially receive some additional verdicts. |
Policy Command
approov policy [option]...
| Option | Description |
-addAnnotateFlag <flag> | Amends the annotation policy so that the given flag will be included in the anno claim of an Approov token if the device property is set. This modification marks the annotation policy as custom. This requires an admin role. |
-addOptionFlag <flag> | Amends the rejection policy so that the specified option flag is enabled. This modification marks the rejection policy as custom. This requires an admin role. |
-addRejectFlag <flag> | Amends the rejection policy so that attestations will be rejected if the specified flag is set. Making a flag level modification such as this marks the rejection policy as custom. This requires an admin role. |
-get | Gets the current security policy being applied to the account. This is provided as a comma separated string composed of the security rules, rejection policy and annotation policy as required by the -set option. More detailed information is also provided including a description of the impact of the current policy settings. The full list of flags, and whether they cause a rejection in the current policy, is also shown. The rejection policy is shown as custom if modifications have been made to the rejection status of individual flags. Note that it is also possible to get this with a pentest role. |
-getARC | Gets the current ARC policy showing if issued Approov tokens will have an arc claim. This may be on or off. If ARC is on then the full list of flags that may be encoded by the value is shown. |
-getARCFlagMappings | Gets the list of global ARC flags that may be encoded in the arc claim of issued Approov tokens. This is only relevant if ARC is enabled. |
-getAudience | Gets the current audience policy showing if issued Approov tokens will have an aud claim. This may be on or off. |
-getInstallPubKey | Gets the current installation public key policy showing if issued Approov tokens will have an ipk claim, if the SDK is able to generate an installation key. This may be on or off. |
-getIPTracking | Gets the current IP tracking setting for the account, which may be token, full or none. |
-getIssuedAt | Gets the current issued-at policy showing if issued Approov tokens will have an iat claim. This may be on or off. |
-getIssuer | Gets the current issuer policy showing if issued Approov tokens will have an iss claim. This may be on or off. |
-getSubject | Gets the current subject policy showing if issued Approov tokens will have an sub claim. This may be on or off. |
-removeAnnotateFlag <flag> | Removes the given flag from the set that may be annotated in an Approov token. Making such a modification marks the annotation policy as custom. |
-removeOptionFlag <flag> | Removes the given flag from the set that are enabled. Making such a modification marks the rejection policy as custom. |
-removeRejectFlag <flag> | Removes the given flag from the set that causes a rejection. Making such a modification marks the rejection policy as custom. |
-set <policy> | This sets the overall security policy for the account. It is provided as three comma separated items as follows in the given order:
A full list of available policy combinations is available in the Security Policies section. Modification of the overall security policy requires an |
-setARC <policy> | Sets the Attestation Response Code (ARC) policy to either being on or off. If the policy is enabled then all issued Approov tokens include an arc claim that provides an encoding of the device properties and whether an issued token was valid or not. This requires an admin role. |
-setAudience <policy> | Sets the audience inclusion policy to either being on or off. If the policy is enabled then all issued Approov tokens include an aud claim providing the domain for which it was issued (or * for wildcard tokens). This may be used as an additional verification by the backend API. This requires an admin role. |
-setInstallPubKey <policy> | Sets the installation public key inclusion policy to either being on or off. If the policy is enabled then all issued Approov tokens include an ipk claim providing the public key for the installation, if that is supported by the SDK being used. This should be used as a signal to the backend that it should expect the inclusion of installation message signatures in requests. This requires an admin role. |
-setIPTracking <setting> | This sets the IP tracking policy for the account as follows:
This requires an |
-setIssuedAt <policy> | Sets the issued-at inclusion policy to either being on or off. If the policy is enabled then all issued Approov tokens include an iat claim providing time at which the token was created. This requires an admin role. |
-setIssuer <policy> | Sets the issuer inclusion policy to either being on or off. If the policy is enabled then all issued Approov tokens include an iss claim providing the account for which the token was issued. This may be used as an additional verification by the backend API. This requires an admin role. |
-setSubject <policy> | Sets the subject inclusion policy to either being on or off. If the policy is enabled then all issued Approov tokens include an sub claim providing the prefix approov| and the device ID to which it was issued followed by | and the app package name. This requires an admin role. |
Secret Command
approov secret [option]...
info
Note that the secret command requires the use of an admin role.
info
These commands relate to the default account secret key. You may also add additional keys using the keyset commands and configure specific API domains to issue tokens signed or encrypted with the keys defined in that set instead.
| Option | Description |
-arc <operation> | This manages the account Attestation Response Code (ARC) encoding secret, with the
An |
-change | This causes the account secret key to be immediately rotated with a new random value that is output by the command. Typically, this should only be done if there is a significant concern that the prior account secret may have been compromised. This change happens immediately so newly generated Approov tokens will use the revised secret. The -forcePrintable option may be added to force the new secret to use printable characters in its raw form. |
-clearKeyID | Clears any key ID that is being included in new JWS tokens signed with the account secret. |
-forcePrintable | This may be used in conjunction with the -change option to force the new account secret to use printable characters in its raw form. This should only be used if your JWT verification library only supports a printable secret. |
-get <representation> | This gets the account secret key in the selected
If the If the The binary secret itself is always 64 bytes (512-bits) in length. It should be integrated into your backend to check the validity of Approov tokens. Note that the secret should be secured with the utmost care, since it allows valid Approov tokens of arbitrary lifetime to be generated. The account secret key itself should never be included in the mobile app or any software in the public domain. |
-getBackendConfig <pathname> | This gets the account backend configuration in JSON format and writes it to the specified pathname. The backend configuration contains all of the data needed by a backend integration to verify and decode the Approov tokens issued for the account. This may be used to integrate with backend systems that need to verify tokens or decode the ARC claim. See Get backend configuration for more details. |
-getJWK <pathname> | This gets the account secret key in the JSON Web Key (JWK) format and writes it to the specified pathname. This may be an easier for integration with those backend systems which support this format. |
-getJWKS <pathname> | This gets the account secret key in the JSON Web Key Set (JWKS) format and writes it to the specified pathname. This may be easier for integration with those backend systems which support this format. |
-getKeyID | Gets the optional key ID that was previously set for the account (using the -setKeyID option). If a key ID is set, then it appears in the kid field in all Approov token JWS headers that are signed using the account secret key. |
-jwe | Can be used in conjunction with the -get to obtain the secret used to encrypt and sign JWE tokens. |
-messageSigningKey <operation> | This manages the message signing key for the account with
The message signing key is always 64 bytes (512-bits) in length. It is used to calculate the HMAC of an arbitrary message input and therefore provides an additional level of integrity checking for all request messages signed in this way. The Approov token should always be included as part of the signed message and must be transmitted alongside the signature for verification before checking the signature; such an approach helps to prevent replay attacks. |
-plain | Can be used in conjunction with the -get option to remove all text except the secret that may normally be output by the command. This may be useful when piping the output to other shell commands. |
-setDeviceID <deviceID> | This sets the example deviceID for use with a -messageSigningKey gen-example-* operation to generate an example token specific secret. |
-setKeyID <kid> | This sets the specific kid to become the label for the account secret and this will appear in the kid field in the header of JWS tokens for the account. This will also be provided in any JWK obtained with -getJWK or -getJWKS. Note that this only impacts tokens using the account secret key. Any tokens issued using a keyset key will contain that key's identifier instead. |
-setExpiry <expiry> | This sets the example expiry time for use with a -messageSigningKey gen-example-* operation to generate an example token specific secret. |
Secrules Command
approov secrules [option]...
| Option | Description |
-current | Used in conjunction with the -set or -remove options to specify that the current security rules versions should be changed. The current versions are those applied to the account and to any custom devices. Exactly one of -current or -new must be specified with -set or -remove. |
-get | Gets all of the security rules version information for the account. This shows which particular versions are selected for particular security rules names, and any new security rules versions that are being selected for some percentage of the devices. |
-list | Lists the security rules versions that are available for use with the -version option. If the security rules versions for your account are managed by Approov then there are no available versions to list. |
-new | Used in conjunction with the -set or -remove options to specify that the new security rules versions should be changed, rather than the current ones. The new versions are used for a subset of the devices in the account, as specified by the new percentage set with -setNewPercent. Exactly one of -current or -new must be specified with -set or -remove. Note that new versions are not applied for device specific security policies. A named version must already exist in the current versions (added with -current) before it can be set as a new version. |
-remove <name> | Removes the version setting for the security rules name. One of -current or -new must be specified to indicate which mapping to remove. Note that it is not possible to remove a current security rules version if it is in use by the account or any custom device. The default security rules name is managed by Approov and cannot be removed. |
-set <name> | Sets the security rules version for the security rules name. The -version option must also be used to specify the version, and one of -current or -new must be specified to indicate which mapping to change. The default security rules name is managed by Approov and cannot be set. |
-setNewPercent <value> | This sets the integer percentage of the devices in the account that should use the new security rules versions, rather than the current security rules versions. This allows the account to be gradually migrated to a new security rules version by increasing this value. Note that this is not applied for device specific security policies. Setting to 0% effectively disables the new security rules version and setting to 100% ensures all devices use the new version. |
-version <value> | This is used in conjunction with -set to specify the particular security rules version that should be associated with the given security rules name. The value provided should be a valid version as provided by the -list option. |
Secure Strings Command
approov secstrings [option]...
| Option | Description |
-addKey <key> | Adds a new predefined string value with the given key. The -predefinedValue option must be used as well to define the value. This either writes a new key/value pair or overwrites an existing one. The maximum number of key/value pairs that may be defined is 16. There is also a 8KB limit on the total storage used for all key/value pairs. Key names cannot be longer than 64 characters. An admin role is required to perform this operation. |
-get | Gets the current state of the secure strings feature. |
-predefinedValue <value> | This is used in conjunction -addKey to define a new predefined key/value pair. |
-removeKey <key> | Removes the predefined secure string with the given key. An admin role is required to perform this operation. |
-setDisabled | Disables the secure strings. Subsequent attempts to fetch a secure string from the app will result in a REJECTED / rejected error. An admin role is required to perform this operation. |
-setEnabled | Enables the use of the secure strings feature. An admin role is required to perform this operation. |
DeviceCheck Command
approov devicecheck [option]...
info
Note that devicecheck commands (apart from -get) requires the use of an admin role. A delegate role may also be used.
| Option | Description |
-addAuthKey <auth-file> | Adds a DeviceCheck key to your account and enables the use of Apple DeviceCheck in your account. The key is downloaded from the Apple developer portal and should be of the form AuthKey_ID.p8, where the ID is the identifier for your particular key. The key must have been granted DeviceCheck privileges. Note that the -teamID option must also be specified. |
-banBit <value> | Apple allows up to two bits to be persisted for each physical device under your Apple developer account. This determines if the setting of these bits will cause the attestation to be failed. Valid options are bit0, bit1 or both. Note that settings older than the expiry duration are ignored, as if the bits were reset. If this option is not used then the device token is just used to prove the presence of a real iOS device. |
-dev | By default the Apple production endpoint (https://api.devicecheck.apple.com) is used. If this option is specified then the development endpoint (https://api.development.devicecheck.apple.com) is used instead. |
-expiry <duration> | This specifies an expiry duration for any device bans in terms of months. This means that if the last update is older than the specified period then the bits are considered to be cleared. The default period is 12 months. The parameter should be specified as a numeric value followed by m (e.g. 1m for one month). |
-get | Gets the current DeviceCheck information. If a key has been added to your account (-addAuthKey) then this checks it against the Apple endpoint and shows a warning if there is an authorization error. |
-remove | Removes the DeviceCheck information from the account. |
-teamID <ID> | This option must be used in conjunction with -addAuthKey and specifies the team identifier for your apps. This identifies apps as being issued by your team and is required in order to make calls to Apple APIs to get and update the DeviceCheck bits. |